Gerenciar plugins

A interface de controle abrange o fluxo de trabalho comum de descoberta, instalação, ativação e desativação. A CLI acrescenta atualização, desinstalação, configuração avançada e controles explícitos da fonte de instalação. Para consultar o contrato completo dos comandos, as opções, as regras de seleção de fonte e os casos extremos, consulte openclaw plugins.

Fluxo de trabalho típico da CLI: encontre um pacote, instale-o pelo ClawHub, npm, git ou por um caminho local, deixe o Gateway gerenciado reiniciar automaticamente (ou reinicie-o manualmente) e, em seguida, verifique os registros de runtime do Plugin.

Usar a interface de controle

Abra Plugins na interface de controle ou use /settings/plugins em relação ao caminho-base configurado da interface de controle. Por exemplo, um caminho-base /openclaw usa /openclaw/settings/plugins. A página tem duas abas:

• Instalados mostra o inventário local completo agrupado por categoria (canais, provedores de modelos, memória e ferramentas). Cada linha abre uma visualização detalhada; seu menu de opções (…) ativa ou desativa o Plugin e, para Plugins instalados externamente, oferece Remover. A aba também lista os servidores MCP configurados com as mesmas ações de ativação, desativação e remoção acionadas por menu, editando mcp.servers na configuração do Gateway.
• Descobrir é a loja: Plugins em destaque incluídos no OpenClaw, Plugins externos oficiais e uma seleção organizada de conectores. Os cartões de conectores adicionam um servidor MCP hospedado com um clique (GitHub, Notion, Linear, Sentry, Home Assistant) ou abrem uma pesquisa pré-preenchida no ClawHub. Digitar na caixa de pesquisa consulta o ClawHub diretamente e acrescenta uma seção Do ClawHub com contagens de downloads e selos de verificação da fonte.

Plugins incluídos não precisam da instalação de um pacote. A ação do menu correspondente é Ativar ou Desativar. O Workboard, por exemplo, está incluído no OpenClaw e desativado por padrão; portanto, escolha Ativar para ativá-lo. Plugins integrados não podem ser removidos, apenas desativados.

O acesso ao catálogo e à pesquisa exige operator.read. Instalação, ativação, desativação, remoção e alterações em servidores MCP exigem operator.admin. Uma instalação pelo ClawHub é realizada pelo Gateway e preserva suas verificações de confiança, integridade e política de instalação de Plugins.

A instalação ou remoção do código de um Plugin exige a reinicialização do Gateway. As alterações de ativação podem ser aplicadas sem reinicialização quando o Plugin instalado e o runtime atual do Gateway oferecem suporte a isso; caso contrário, a interface informa que uma reinicialização é necessária. Os conectores MCP com OAuth ainda precisam de uma execução única de openclaw mcp login <name> pela CLI após serem adicionados.

A interface de controle não instala a partir de fontes npm, git ou caminhos locais arbitrários, não atualiza Plugins nem oferece configurações avançadas de Plugins. Use os fluxos de trabalho da CLI abaixo para essas operações.

Listar e pesquisar Plugins

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search "calendar"

--json para scripts:

openclaw plugins list --json \  | jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'

plugins list é uma verificação a frio do inventário: o que o OpenClaw consegue descobrir por meio da configuração, dos manifestos e do registro persistente de Plugins. Isso não comprova que um Gateway já em execução importou o runtime do Plugin. A saída JSON inclui diagnósticos do registro e o dependencyStatus de cada Plugin (se as dependencies/optionalDependencies declaradas podem ser resolvidas no disco).

plugins search consulta o ClawHub em busca de pacotes de Plugins instaláveis e exibe uma sugestão de instalação (openclaw plugins install clawhub:<package>) para cada resultado.

Ativar e desativar Plugins

openclaw plugins enable <plugin-id>openclaw plugins disable <plugin-id>

Alterna a entrada de configuração de um Plugin sem alterar os arquivos instalados. Alguns Plugins integrados (provedores integrados de modelos/fala e o Plugin integrado de navegador) são ativados por padrão; outros exigem enable após a instalação.

Instalar Plugins

# Pesquisar pacotes de Plugins no ClawHub.openclaw plugins search "calendar" # Instalar pelo ClawHub.openclaw plugins install clawhub:<package>openclaw plugins install clawhub:<package>@1.2.3openclaw plugins install clawhub:<package>@beta # Instalar pelo npm.openclaw plugins install npm:<package>openclaw plugins install npm:@scope/openclaw-plugin@1.2.3openclaw plugins install npm:@openclaw/codex # Instalar a partir de um artefato npm-pack local.openclaw plugins install npm-pack:<path.tgz> # Instalar pelo git ou por um checkout de desenvolvimento local.openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

Especificações de pacote sem prefixo são instaladas pelo npm durante a transição de lançamento, a menos que o nome corresponda ao id de um Plugin integrado ou oficial; nesse caso, o OpenClaw usa essa cópia local/oficial. Use clawhub:, npm:, git: ou npm-pack: para selecionar a fonte de forma determinística.

Use --force somente para sobrescrever um destino de instalação existente proveniente de outra fonte. Para atualizações rotineiras de uma instalação npm, ClawHub ou de pacote de hooks rastreada, use openclaw plugins update; --force não é compatível com --link.

Reiniciar e inspecionar

Um Gateway gerenciado em execução com o recarregamento de configuração ativado reinicia automaticamente após a instalação, atualização ou desinstalação do código de um Plugin. Se o Gateway não for gerenciado ou o recarregamento estiver desativado, reinicie-o manualmente antes de verificar as superfícies de runtime ativas:

openclaw gateway restartopenclaw plugins inspect <plugin-id> --runtime --json

inspect --runtime carrega o módulo do Plugin e comprova que ele registrou superfícies de runtime (ferramentas, hooks, serviços, métodos do Gateway, rotas HTTP e comandos da CLI pertencentes ao Plugin). inspect sem opções e list são apenas verificações a frio de manifesto, configuração e registro.

Atualizar Plugins

openclaw plugins update <plugin-id>openclaw plugins update <npm-package-or-spec>openclaw plugins update --allopenclaw plugins update <plugin-id> --dry-run

Fornecer o id de um Plugin reutiliza sua especificação de instalação rastreada: dist-tags armazenadas (@beta) e versões exatas fixadas são mantidas nas execuções posteriores de update <plugin-id>.

openclaw plugins update --all é o caminho de manutenção em massa. Ele ainda respeita as especificações comuns de instalação rastreadas, mas os registros confiáveis de Plugins oficiais do OpenClaw são sincronizados com o destino atual do catálogo oficial, em vez de permanecerem fixados em um pacote oficial exato e desatualizado; quando update.channel é beta, essa sincronização dá preferência à linha de versões beta. Use um update <plugin-id> direcionado para manter intacta uma especificação oficial exata ou marcada.

Para instalações pelo npm, forneça uma especificação de pacote explícita para alterar o registro rastreado:

openclaw plugins update @scope/openclaw-plugin@betaopenclaw plugins update @scope/openclaw-plugin

O segundo comando move um Plugin de volta para a linha de versões padrão do registro quando ele estava anteriormente fixado em uma versão exata ou tag.

Consulte openclaw plugins para conhecer as regras exatas de fallback e fixação.

Desinstalar Plugins

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

A desinstalação remove a entrada de configuração do Plugin, o registro persistente do índice de Plugins, as entradas das listas de permissões/negações e as entradas vinculadas de plugins.load.paths, quando aplicável. O diretório de instalação gerenciado é removido, a menos que você use --keep-files. Um Gateway gerenciado em execução reinicia automaticamente quando a desinstalação altera a fonte do Plugin.

No modo Nix (OPENCLAW_NIX_MODE=1), a instalação, atualização, desinstalação, ativação e desativação de Plugins ficam desabilitadas; gerencie essas escolhas na fonte Nix da instalação.

Escolher uma fonte

As instalações gerenciadas por caminho local devem ser diretórios ou arquivos compactados de Plugins. Coloque arquivos independentes de Plugins em plugins.load.paths em vez de instalá-los com plugins install.

Publicar Plugins

O ClawHub é a principal superfície pública de descoberta de Plugins do OpenClaw. Publique nele quando quiser que os usuários encontrem metadados do Plugin, histórico de versões, resultados das verificações do registro e sugestões de instalação antes de instalar.

npm i -g clawhubclawhub loginclawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-pluginclawhub package publish your-org/your-plugin@v1.0.0

Plugins npm nativos devem incluir um manifesto de Plugin (openclaw.plugin.json) e metadados no package.json antes da publicação:

{  "name": "@acme/openclaw-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

npm publish --access publicopenclaw plugins install npm:@acme/openclaw-pluginopenclaw plugins install npm:@acme/openclaw-plugin@betaopenclaw plugins install npm:@acme/openclaw-plugin@1.0.0

Use estas páginas para consultar o contrato completo de publicação, em vez de tratar esta página como referência de publicação:

• Publicação no ClawHub explica proprietários, escopos, versões, revisão, validação e transferência de pacotes.
• Criação de Plugins mostra a estrutura completa do pacote do Plugin (incluindo openclaw.plugin.json) e o fluxo de trabalho da primeira publicação.
• Manifesto de Plugin define os campos do manifesto de Plugin nativo.

Se o mesmo pacote estiver disponível no ClawHub e no npm, use o prefixo explícito clawhub: ou npm: para forçar uma das fontes.

Relacionados

• Plugins - instalar, configurar, reiniciar e solucionar problemas
• openclaw plugins - referência completa da CLI
• Plugins da comunidade - descoberta pública e publicação no ClawHub
• ClawHub - operações da CLI do registro
• Criação de Plugins - criar um pacote de Plugin
• Manifesto de Plugin - manifesto e metadados do pacote