Gerencie plugins do Gateway, pacotes de hooks e bundles compatíveis.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
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.
No modo Nix (
OPENCLAW_NIX_MODE=1), mutadores de ciclo de vida de plugins ficam desabilitados. Use a origem Nix para esta instalação em vez de plugins install, plugins update, plugins uninstall, plugins enable ou plugins disable; para nix-openclaw, use o Início rápido orientado ao agente.Plugins integrados são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelos integrados, provedores de fala integrados e o plugin de navegador integrado); outros exigem
plugins enable.Plugins nativos do OpenClaw devem incluir openclaw.plugin.json com um JSON Schema inline (configSchema, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.plugins list mostra Format: openclaw ou Format: bundle. A saída detalhada de list/info também mostra o subtipo do bundle (codex, claude ou cursor) mais os recursos de bundle detectados.Instalar
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.
ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. Npm
permanece como fallback compatível e caminho de instalação direta. Pacotes de plugins
@openclaw/* mantidos pelo OpenClaw são publicados novamente no npm; veja a lista atual
em npmjs.com/org/openclaw ou no
inventário de plugins. Instalações estáveis usam latest.
Instalações e atualizações do canal beta preferem a dist-tag beta do npm quando essa tag
está disponível, depois recorrem a latest.Includes de configuração e reparo de configuração inválida
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 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
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/plugin@v1.2.3, 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
--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
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
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
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.clawhub:<package>:
npm: para tornar explícita a resolução exclusiva por npm:
.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:pkg@1.2.3 e clawhub:pkg@beta, permanecem fixados nesse seletor.
Abreviação de marketplace
Use a abreviaçãoplugin@marketplace quando o nome do marketplace existir no cache de registro local do Claude em ~/.claude/plugins/known_marketplaces.json:
--marketplace quando quiser passar a origem do marketplace explicitamente:
- Origens de marketplace
- Regras de marketplace remoto
- 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
- 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) - pacotes compatíveis com Cursor (
.cursor-plugin/plugin.json)
Pacotes compatíveis são instalados na raiz normal de Plugins e participam do mesmo fluxo de listar/informações/ativar/desativar. Atualmente, há suporte para Skills de pacote, command-skills do Claude, padrões de
settings.json do Claude, padrões de .lsp.json do Claude / lspServers declarados no manifesto, command-skills do Cursor e diretórios de hooks compatíveis do Codex; outras capacidades de pacote detectadas são mostradas em diagnósticos/informações, mas ainda não estão conectadas à execução em runtime.Listar
Mostra apenas Plugins ativados.
Alterna da visualização em tabela para linhas de detalhes por Plugin com metadados de origem/procedência/versão/ativação.
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacote.
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 --jsonmostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; useopenclaw doctor --fixpara limpar estado legado de dependências ou recuperar Plugins baixáveis ausentes que são referenciados pela configuração.openclaw gateway status --deep --require-rpcconfirma 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) exigemplugins.entries.<id>.hooks.allowConversationAccess=true.
--link para evitar copiar um diretório local (adiciona a plugins.load.paths):
--force não é compatível com --link porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.Use --pin em instalações npm para salvar a especificação exata resolvida (name@version) no índice de Plugins gerenciado, mantendo o comportamento padrão sem fixação.Í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 emplugins/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
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.
--keep-config é compatível como alias obsoleto de --keep-files.Atualizar
hooks.internal.installs.
Resolver id de Plugin vs especificação npm
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
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
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 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
--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
A flag
--json gera um relatório legível por máquina, adequado para scripts e auditoria. inspect --all renderiza uma tabela de toda a frota com colunas de formato, tipos de capability, avisos de compatibilidade, capabilities do pacote e resumo de hooks. info é um alias para inspect.Diagnóstico
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
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
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.