---
read_when:
- Você deseja instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
- Você quer depurar falhas de carregamento de Plugin
sidebarTitle: Plugins
summary: Referência da CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Plugins
x-i18n:
generated_at: "2026-05-12T08:45:44Z"
model: gpt-5.5
provider: openai
source_hash: 4b51646a103e9e020f6e53cd08aa25e7291fb629741fd41bdab520d80b7416ff
source_path: cli/plugins.md
workflow: 16
---
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
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search
openclaw plugins search --limit 20
openclaw plugins search --json
openclaw plugins install
openclaw plugins inspect
openclaw plugins inspect --runtime
openclaw plugins inspect --json
openclaw plugins inspect --all
openclaw plugins info
openclaw plugins enable
openclaw plugins disable
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall
openclaw plugins doctor
openclaw plugins update
openclaw plugins update --all
openclaw plugins marketplace list
openclaw plugins marketplace list --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](/pt-BR/help/debugging#plugin-lifecycle-trace).
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](https://github.com/openclaw/nix-openclaw#quick-start) 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
```bash
openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install # npm by default
openclaw plugins install clawhub: # ClawHub only
openclaw plugins install npm: # npm only
openclaw plugins install npm-pack: # local npm pack through npm install semantics
openclaw plugins install git:github.com// # git repo
openclaw plugins install git:github.com//@
openclaw plugins install --force # overwrite existing install
openclaw plugins install --pin # pin version
openclaw plugins install --dangerously-force-unsafe-install
openclaw plugins install # local path
openclaw plugins install @ # marketplace
openclaw plugins install --marketplace # marketplace (explicit)
openclaw plugins install --marketplace https://github.com//
```
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](/pt-BR/plugins/install-overrides).
Nomes de pacotes sem prefixo instalam a partir do npm por padrão durante a transição de lançamento. Use `clawhub:` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
`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](https://www.npmjs.com/org/openclaw) ou no
[inventário de plugins](/pt-BR/plugins/plugin-inventory). 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`.
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](/pt-BR/gateway/configuration) 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` 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 `.
Se você executar `plugins install` para um id de plugin que já está instalado, o OpenClaw para e aponta para `plugins update ` para uma atualização normal, ou para `plugins install --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
`--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` é 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](/pt-BR/clawhub/security).
`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:` 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`).
Use `git:` 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 `@` ou `#` 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 --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 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:` 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:`:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
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-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
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:pkg@1.2.3` 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
openclaw plugins install @
```
Use `--marketplace` quando quiser passar a origem do marketplace explicitamente:
```bash
openclaw plugins install --marketplace
openclaw plugins install --marketplace
openclaw plugins install --marketplace https://github.com//
openclaw plugins install --marketplace ./my-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
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`)
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
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search
openclaw plugins search --limit 20
openclaw plugins search --json
```
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:`.
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 --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..hooks.allowConversationAccess=true`.
Use `--link` para evitar copiar um diretório local (adiciona a `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
`--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 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
openclaw plugins uninstall --dry-run
openclaw plugins uninstall --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`.
`--keep-config` é compatível como alias obsoleto de `--keep-files`.
### Atualizar
```bash
openclaw plugins update
openclaw plugins update --all
openclaw plugins update --dry-run
openclaw plugins update @openclaw/voice-call
openclaw 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`.
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 `.
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.
`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.
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` 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
openclaw plugins inspect --runtime
openclaw plugins inspect --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](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de capability.
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
```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.` 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 registry
openclaw plugins registry --refresh
openclaw 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.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma chave de compatibilidade obsoleta de último recurso para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback de env é apenas para recuperação emergencial de inicialização enquanto a migração é implantada.
### Marketplace
```bash
openclaw plugins marketplace list
openclaw plugins marketplace list --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
- [Criando plugins](/pt-BR/plugins/building-plugins)
- [Referência da CLI](/pt-BR/cli)
- [ClawHub](/pt-BR/clawhub)