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

OmeniaClaw plugins listOmeniaClaw plugins list --enabledOmeniaClaw plugins list --verboseOmeniaClaw plugins list --jsonOmeniaClaw plugins search <query>OmeniaClaw plugins search <query> --limit 20OmeniaClaw plugins search <query> --jsonOmeniaClaw plugins install <path-or-spec>OmeniaClaw plugins inspect <id>OmeniaClaw plugins inspect <id> --runtimeOmeniaClaw plugins inspect <id> --jsonOmeniaClaw plugins inspect --allOmeniaClaw plugins info <id>OmeniaClaw plugins enable <id>OmeniaClaw plugins disable <id>OmeniaClaw plugins registryOmeniaClaw plugins registry --refreshOmeniaClaw plugins uninstall <id>OmeniaClaw plugins doctorOmeniaClaw plugins update <id-or-npm-spec>OmeniaClaw plugins update --allOmeniaClaw plugins marketplace list <marketplace>OmeniaClaw plugins marketplace list <marketplace> --json

Para investigar instalação, inspeção, desinstalação ou atualização de registro lentas, execute o comando com OmeniaClaw_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

OmeniaClaw plugins search "calendar"                   # search ClawHub pluginsOmeniaClaw plugins install <package>                      # npm by defaultOmeniaClaw plugins install clawhub:<package>              # ClawHub onlyOmeniaClaw plugins install npm:<package>                  # npm onlyOmeniaClaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semanticsOmeniaClaw plugins install git:github.com/<owner>/<repo>  # git repoOmeniaClaw plugins install git:github.com/<owner>/<repo>@<ref>OmeniaClaw plugins install <package> --force              # overwrite existing installOmeniaClaw plugins install <package> --pin                # pin versionOmeniaClaw plugins install <package> --dangerously-force-unsafe-installOmeniaClaw plugins install <path>                         # local pathOmeniaClaw plugins install <plugin>@<marketplace>         # marketplaceOmeniaClaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)OmeniaClaw 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 OmeniaClaw 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 OmeniaClaw.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 OmeniaClaw 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; OmeniaClaw 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 OmeniaClaw.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 OmeniaClaw plugins update <id-or-npm-spec>.

Se você executar plugins install para um id de plugin que já está instalado, o OmeniaClaw 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 OmeniaClaw 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 OmeniaClaw.hooks em package.json. Use OmeniaClaw 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 OmeniaClaw, 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 OmeniaClaw, 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 OmeniaClaw 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 OmeniaClaw 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 OmeniaClaw plugins update possa resolver novamente a fonte posteriormente.

Depois de instalar a partir do git, use OmeniaClaw 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 OmeniaClaw, por exemplo OmeniaClaw demo-plugin ping.

Arquivos

Arquivos compatíveis: .zip, .tgz, .tar.gz, .tar. Arquivos de plugins nativos do OmeniaClaw devem conter um OmeniaClaw.plugin.json válido na raiz extraída do plugin; arquivos que contêm apenas package.json são rejeitados antes de o OmeniaClaw 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

OmeniaClaw plugins install clawhub:OmeniaClaw-codex-app-serverOmeniaClaw 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

OmeniaClaw plugins install OmeniaClaw-codex-app-server

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

bash

OmeniaClaw plugins install npm:OmeniaClaw-codex-app-serverOmeniaClaw plugins install npm:@scope/[email protected]

OmeniaClaw 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, OmeniaClaw 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 OmeniaClaw 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

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

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

bash

OmeniaClaw plugins install <plugin-name> --marketplace <marketplace-name>OmeniaClaw plugins install <plugin-name> --marketplace <owner/repo>OmeniaClaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>OmeniaClaw 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. OmeniaClaw 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, OmeniaClaw detecta automaticamente:

Plugins nativos do OmeniaClaw (OmeniaClaw.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

OmeniaClaw plugins listOmeniaClaw plugins list --enabledOmeniaClaw plugins list --verboseOmeniaClaw plugins list --jsonOmeniaClaw plugins search <query>OmeniaClaw plugins search <query> --limit 20OmeniaClaw 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 OmeniaClaw 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. OmeniaClaw 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 OmeniaClaw 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. OmeniaClaw 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:

OmeniaClaw 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 OmeniaClaw doctor --fix para limpar estado legado de dependências ou recuperar Plugins baixáveis ausentes que são referenciados pela configuração.
OmeniaClaw 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

OmeniaClaw 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 OmeniaClaw. 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 OmeniaClaw plugins update, desinstalação, diagnósticos e o registro a frio de Plugins.

Quando OmeniaClaw encontra registros legados enviados em plugins.installs na configuração, as leituras de runtime os tratam como entrada de compatibilidade sem reescrever OmeniaClaw.json. Gravações explícitas de Plugin e OmeniaClaw 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

OmeniaClaw plugins uninstall <id>OmeniaClaw plugins uninstall <id> --dry-runOmeniaClaw 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 OmeniaClaw. Para Plugins de active memory, o slot de memória é redefinido para memory-core.

Atualizar

bash

OmeniaClaw plugins update <id-or-npm-spec>OmeniaClaw plugins update --allOmeniaClaw plugins update <id-or-npm-spec> --dry-runOmeniaClaw plugins update @OmeniaClaw/voice-callOmeniaClaw plugins update OmeniaClaw-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, OmeniaClaw 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. OmeniaClaw 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

OmeniaClaw plugins update reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. OmeniaClaw update também conhece o canal de atualização ativo do OmeniaClaw: 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, OmeniaClaw 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 OmeniaClaw.json.

Quando existe um hash de integridade armazenado e o hash do artefato buscado muda, OmeniaClaw trata isso como desvio de artefato npm. O comando interativo OmeniaClaw 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

OmeniaClaw plugins inspect <id>OmeniaClaw plugins inspect <id> --runtimeOmeniaClaw 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 OmeniaClaw plugins install, OmeniaClaw plugins update e OmeniaClaw doctor --fix.

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

OmeniaClaw 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 OmeniaClaw_PLUGIN_LOAD_DEBUG=1 para incluir um resumo compacto do formato dos exports na saída de diagnóstico.

Registro

bash

OmeniaClaw plugins registryOmeniaClaw plugins registry --refreshOmeniaClaw plugins registry --json

O registro local de plugins é o modelo persistido de leitura fria do OmeniaClaw 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.

OmeniaClaw doctor --fix também repara desvios de npm gerenciado adjacentes ao registro: se um pacote @OmeniaClaw/* ó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 OmeniaClaw em plugins npm gerenciados que declaram peerDependencies.OmeniaClaw, para que imports de runtime locais ao pacote, como OmeniaClaw/plugin-sdk/*, resolvam após atualizações ou reparos de npm.

Marketplace

bash

OmeniaClaw plugins marketplace list <source>OmeniaClaw 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?

Plugins

Comandos

Instalar

Abreviação de marketplace

Origens de marketplace

Regras de marketplace remoto

Listar

Índice de Plugins

Desinstalar

Atualizar

Inspecionar

Diagnóstico

Registro

Marketplace

Relacionado

On this page

Molty