Plugins

Plugins estendem o OpenClaw com canais, provedores de modelo, harnesses de agente, ferramentas, skills, fala, transcrição em tempo real, voz, entendimento de mídia, geração, busca web, pesquisa web e outros recursos de runtime.

Use esta página quando quiser instalar um plugin, reiniciar o Gateway, verificar se o runtime o carregou e encaminhar falhas comuns de configuração. Para exemplos somente de comandos, consulte Gerenciar plugins. Para o inventário completo gerado de plugins integrados, externos oficiais e somente de código-fonte, consulte Inventário de plugins.

Requisitos

Antes de instalar um plugin, certifique-se de ter:

• um checkout ou instalação do OpenClaw com a CLI openclaw disponível
• acesso de rede à origem selecionada, como ClawHub, npm ou um host git
• quaisquer credenciais, chaves de configuração ou ferramentas de sistema operacional específicas do plugin nomeadas pela documentação de configuração desse plugin
• permissão para o Gateway que atende seus canais recarregar ou reiniciar

Início rápido

openclaw plugins search "calendar"

# Do ClawHub.openclaw plugins install clawhub:<package> # Do npm.openclaw plugins install npm:<package> # Do git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # De um checkout de desenvolvimento local.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

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

Configuração

Escolher uma origem de instalação

Especificações de pacote sem prefixo têm comportamento especial de compatibilidade. Se o nome sem prefixo corresponder a um id de plugin integrado, o OpenClaw usa essa origem integrada. Se corresponder a um id de plugin externo oficial, o OpenClaw usa o catálogo oficial de pacotes. Outras especificações comuns de pacote sem prefixo são instaladas pelo npm durante a transição de lançamento. Especificações brutas de pacote @openclaw/* que correspondem a plugins integrados também resolvem para a cópia integrada antes do fallback para npm. Use npm:@openclaw/<plugin>@<version> quando você quiser deliberadamente o pacote npm externo em vez da cópia integrada pertencente à imagem. Use clawhub:, npm:, git: ou npm-pack: quando precisar de seleção determinística de origem. Consulte openclaw plugins para o contrato completo do comando.

Para instalações npm, especificações de pacote sem versão fixa e @latest escolhem o pacote estável mais recente que anuncia compatibilidade com esta compilação do OpenClaw. Se a versão latest atual do npm declarar um openclaw.compat.pluginApi ou openclaw.install.minHostVersion mais novo, o OpenClaw verifica versões estáveis de pacote mais antigas e instala a mais nova que se encaixa. Versões exatas e tags de canal explícitas como @beta permanecem fixadas ao pacote selecionado e falham quando incompatíveis.

Política de instalação do operador

Configure security.installPolicy para executar um comando de política local confiável antes que a instalação ou atualização do plugin prossiga. A política recebe metadados mais o caminho de origem preparado e pode permitir ou bloquear a instalação. Ela cobre caminhos de instalação/atualização de plugins via CLI e baseados no Gateway. Hooks before_install de plugins são executados depois apenas em processos OpenClaw em que hooks de plugins são carregados, então use security.installPolicy para decisões de instalação pertencentes ao operador. A flag obsoleta --dangerously-force-unsafe-install é aceita por compatibilidade, mas não ignora a política de instalação nem a denylist integrada de dependências de plugins do OpenClaw.

Consulte Configuração de Skills para o schema exec compartilhado de security.installPolicy usado por skills e plugins.

Configurar política de plugins

O formato comum de configuração de plugins é:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Regras principais de política:

• plugins.enabled: false desabilita todos os plugins e pula o trabalho de descoberta/carregamento de plugins. Referências obsoletas a plugins ficam inertes enquanto isso está ativo; reabilite plugins antes de executar a limpeza do doctor quando quiser remover ids obsoletos.
• plugins.deny prevalece sobre allow e habilitação por plugin.
• plugins.allow é uma allowlist exclusiva. Ferramentas pertencentes a plugins fora da allowlist permanecem indisponíveis, mesmo quando tools.allow inclui "*".
• plugins.entries.<id>.enabled: false desabilita um plugin enquanto preserva sua configuração.
• plugins.load.paths adiciona arquivos ou diretórios explícitos de plugins locais. Caminhos locais gerenciados por plugins install devem ser diretórios ou arquivos compactados de plugin; use plugins.load.paths para arquivos de plugin independentes.
• Plugins originados do workspace são desabilitados por padrão; habilite-os explicitamente ou coloque-os na allowlist antes de usar código local do workspace.
• Plugins integrados seguem seus metadados integrados default-on/default-off, a menos que a configuração os substitua explicitamente.
• plugins.slots.<slot> escolhe um plugin para categorias exclusivas como mecanismos de memória e contexto. A seleção de slot força a habilitação do plugin selecionado para esse slot ao contar como ativação explícita; ele pode carregar mesmo quando de outra forma seria opt-in. plugins.deny e plugins.entries.<id>.enabled: false ainda o bloqueiam.
• Plugins integrados opt-in podem ser ativados automaticamente quando a configuração nomeia uma de suas superfícies pertencentes, como uma ref de provedor/modelo, configuração de canal, backend de CLI ou runtime de harness de agente.
• O roteamento de Codex da família OpenAI mantém os limites de plugin de provedor e runtime separados: refs de modelos Codex legadas são configuração legada reparada pelo doctor, enquanto o plugin integrado codex possui o runtime do servidor de aplicativo Codex para refs de agente canônicas openai/*, agentRuntime.id: "codex" explícito e refs legadas codex/*.

Quando plugins.allow não está definido e plugins não integrados são descobertos automaticamente a partir do workspace ou raízes globais de plugins, os logs de inicialização registram plugins.allow is empty; discovered non-bundled plugins may auto-load: .... O aviso inclui ids de plugins descobertos e, para listas curtas, um snippet mínimo de plugins.allow. Execute openclaw plugins list --enabled --verbose ou openclaw plugins inspect <id> com o id do plugin listado antes de copiar plugins confiáveis para openclaw.json. A mesma orientação de fixação de confiança se aplica quando diagnósticos dizem que um plugin carregou without install/load-path provenance: inspecione esse id de plugin e então fixe o id confiável em plugins.allow ou reinstale a partir de uma origem confiável para que o OpenClaw registre a proveniência da instalação.

Execute openclaw doctor ou openclaw doctor --fix quando a validação de configuração relatar ids de plugins obsoletos, incompatibilidades de allowlist/ferramentas ou caminhos legados de plugins integrados.

Entender formatos de plugins

O OpenClaw reconhece dois formatos de plugin:

Ambos os formatos aparecem em openclaw plugins list, openclaw plugins inspect, openclaw plugins enable e openclaw plugins disable. Consulte Bundles de plugins para o limite de compatibilidade de bundles e Criando plugins para autoria de plugins nativos.

Hooks de plugins

Plugins podem registrar hooks em runtime, mas há duas APIs diferentes com trabalhos diferentes.

• Use hooks tipados via api.on(...) para hooks de ciclo de vida do runtime. Esta é a superfície preferida para middleware, política, reescrita de mensagens, modelagem de prompts e controle de ferramentas.
• Use api.registerHook(...) somente quando quiser participar do sistema interno de hooks descrito em Hooks. Isso é principalmente para efeitos colaterais amplos de comandos/ciclo de vida e compatibilidade com automação existente no estilo HOOK.

Regra rápida:

• Se o handler precisar de prioridade, semântica de mesclagem ou comportamento de bloquear/cancelar, use hooks tipados de plugin.
• Se o handler apenas reagir a command:new, command:reset, message:sent, ou eventos amplos semelhantes, api.registerHook(...) é adequado.

Hooks internos gerenciados por plugin aparecem em openclaw hooks list com plugin:<id>. Você não pode habilitá-los ou desabilitá-los por meio de openclaw hooks; em vez disso, habilite ou desabilite o plugin.

Verificar o Gateway ativo

openclaw plugins list e openclaw plugins inspect simples leem configuração, manifesto e estado do registro em frio. Eles não comprovam que um Gateway já em execução importou o mesmo código de plugin.

Quando um plugin aparece instalado, mas o tráfego de chat ativo não o usa:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Gateways gerenciados reiniciam automaticamente após alterações de instalação, atualização e desinstalação de plugins que alteram o código-fonte do plugin. Em instalações em VPS ou contêiner, certifique-se de que qualquer reinicialização manual tenha como alvo o processo filho real de openclaw gateway run que atende seus canais, não apenas um wrapper ou supervisor.

Solução de problemas

Quando uma configuração obsoleta de plugin ainda nomeia um plugin de canal que não pode mais ser descoberto, a inicialização do Gateway ignora esse canal com suporte de plugin em vez de bloquear todos os outros canais. Execute openclaw doctor --fix para remover entradas obsoletas de plugin e canal. Chaves de canal desconhecidas sem evidência de plugin obsoleto ainda falham na validação para que erros de digitação continuem visíveis.

Para substituição intencional de canal, o plugin preferido deve declarar channelConfigs.<channel-id>.preferOver com o id do plugin legado ou de menor prioridade. Se ambos os plugins estiverem explicitamente habilitados, o OpenClaw mantém essa solicitação e relata diagnósticos de canal ou ferramenta duplicados em vez de escolher silenciosamente um proprietário.

Se um pacote instalado informar que ele requires compiled runtime output for TypeScript entry ..., o pacote foi publicado sem os arquivos JavaScript de que o OpenClaw precisa em runtime. Atualize ou reinstale depois que o publicador enviar JavaScript compilado, ou desabilite/desinstale o plugin até lá.

Propriedade de caminho de plugin bloqueada

Se os diagnósticos de plugin disserem blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) e a validação de configuração vier em seguida com plugin present but blocked, o OpenClaw encontrou arquivos de plugin pertencentes a um usuário Unix diferente daquele do processo que os está carregando. Mantenha a configuração do plugin em vigor; corrija a propriedade do sistema de arquivos ou execute o OpenClaw como o mesmo usuário que possui o diretório de estado.

Para instalações Docker, a imagem oficial executa como node (uid 1000), portanto os diretórios de configuração e workspace do OpenClaw montados por bind no host normalmente devem pertencer ao uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Se você executar intencionalmente o OpenClaw como root, corrija a raiz de plugins gerenciada para propriedade de root:

sudo chown -R root:root /path/to/openclaw-config/npm

Depois de corrigir a propriedade, execute novamente openclaw doctor --fix ou openclaw plugins registry --refresh para que o registro de plugins persistido corresponda aos arquivos corrigidos.

Configuração lenta de ferramentas de plugin

Se os turnos do agente parecerem travar durante a preparação de ferramentas, habilite o registro em log de rastreamento e procure linhas de temporização de factory de ferramentas de plugin:

openclaw config set logging.level traceopenclaw logs --follow

Procure por:

[trace:plugin-tools] factory timings ...

O resumo lista o tempo total de factory e as factories de ferramentas de plugin mais lentas, incluindo id do plugin, nomes de ferramentas declarados, formato do resultado e se a ferramenta é opcional. Linhas lentas são promovidas a avisos quando uma única factory leva pelo menos 1s ou quando a preparação total de factories de ferramentas de plugin leva pelo menos 5s.

O OpenClaw armazena em cache resultados bem-sucedidos de factories de ferramentas de plugin para resoluções repetidas com o mesmo contexto efetivo da solicitação. A chave do cache inclui a configuração efetiva de runtime, o workspace, ids de agente/sessão, política de sandbox, configurações do navegador, contexto de entrega, identidade do solicitante e estado de propriedade, portanto factories que dependem desses campos confiáveis são executadas novamente quando o contexto muda. Se as temporizações continuarem altas, o plugin pode estar fazendo trabalho caro antes de retornar suas definições de ferramentas.

Se um plugin dominar a temporização, inspecione seus registros de runtime:

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

Depois atualize, reinstale ou desabilite esse plugin. Autores de plugins devem mover carregamentos caros de dependências para trás do caminho de execução da ferramenta em vez de fazê-los dentro da factory da ferramenta.

Para raízes de dependência, validação de metadados de pacote, registros de registro, comportamento de recarregamento na inicialização e limpeza legada, consulte Resolução de dependências de plugins.

Relacionados

• Gerenciar plugins - exemplos de comandos para listar, instalar, atualizar, desinstalar e publicar
• openclaw plugins - referência completa da CLI
• Inventário de plugins - lista gerada de plugins empacotados e externos
• Referência de plugins - páginas de referência geradas por plugin
• Plugins da comunidade - descoberta no ClawHub e política de PRs de documentação
• Resolução de dependências de plugins - raízes de instalação, registros de registro e limites de runtime
• Criação de plugins - guia de autoria de plugins nativos
• Visão geral do Plugin SDK - registro de runtime, hooks e campos de API
• Manifesto de plugin - metadados de manifesto e pacote