Plugins

Plugins ampliam o OpenClaw com canais, provedores de modelos, estruturas de agentes, ferramentas, skills, fala, transcrição em tempo real, voz, compreensão de mídia, geração, busca de conteúdo web, pesquisa na web e outros recursos de runtime.

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

Requisitos

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

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 fonte de instalação

Especificações simples de pacotes têm um comportamento especial de compatibilidade: um nome simples que corresponda ao id de um plugin integrado usa essa fonte integrada; um nome simples que corresponda ao id de um plugin externo oficial usa o catálogo oficial de pacotes; qualquer outra especificação simples é instalada pelo npm durante a transição de lançamento. Especificações @openclaw/* brutas que correspondam a plugins integrados também são resolvidas para a cópia integrada antes do fallback para o npm. Use npm:@openclaw/<plugin>@<version> para instalar deliberadamente o pacote npm externo em vez da cópia integrada. Use clawhub:, npm:, git: ou npm-pack: para uma seleção determinística da fonte. Consulte openclaw plugins para ver o contrato completo do comando.

Em instalações pelo npm, especificações sem versão fixada e @latest selecionam o pacote estável mais recente que declara 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 recente do que o compatível com esta compilação, o OpenClaw verifica versões estáveis anteriores e instala a mais recente que seja compatível. Versões exatas e tags explícitas de canais, como @beta, permanecem fixadas no pacote selecionado e falham quando são 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 de um plugin prossiga. A política recebe metadados e o caminho da fonte preparada e pode permitir ou bloquear a instalação. Ela abrange tanto os caminhos de instalação/atualização da CLI quanto os baseados no Gateway. Os hooks before_install do plugin são executados posteriormente e somente nos processos do OpenClaw em que os hooks do plugin estão carregados; portanto, use security.installPolicy para decisões de instalação pertencentes ao operador. A opção obsoleta --dangerously-force-unsafe-install é aceita por compatibilidade, mas não realiza nenhuma ação: ela não ignora a política de instalação nem a lista de bloqueio integrada do OpenClaw para dependências de plugins.

Consulte Configuração de Skills para ver o esquema compartilhado de execução security.installPolicy usado por skills e plugins.

Configurar a 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" } },    },  },}

Principais regras da política:

• plugins.enabled: false desabilita todos os plugins e ignora o trabalho de descoberta/carregamento. Referências obsoletas a plugins permanecem inertes enquanto isso estiver ativo; reabilite os plugins antes de executar a limpeza do doctor se quiser remover ids obsoletos.
• plugins.deny prevalece sobre a lista de permissões e a habilitação individual dos plugins.
• plugins.allow é uma lista de permissões exclusiva. Ferramentas pertencentes a plugins fora da lista de permissões permanecem indisponíveis mesmo quando tools.allow inclui "*".
• plugins.entries.<id>.enabled: false desabilita um plugin sem remover sua configuração.
• plugins.load.paths adiciona arquivos ou diretórios locais explícitos de plugins. Caminhos locais gerenciados em plugins install devem ser diretórios ou arquivos compactados de plugins; use plugins.load.paths para arquivos independentes de plugins.
• Plugins originados do workspace são desabilitados por padrão; habilite-os explicitamente ou adicione-os à lista de permissões antes de usar código do workspace local.
• Plugins integrados seguem seus metadados internos de ativação/desativação padrão, a menos que a configuração os substitua explicitamente.
• plugins.slots.<slot> (memory ou contextEngine) seleciona um plugin para uma categoria exclusiva. A seleção de slot conta como ativação explícita e força a habilitação do plugin selecionado para esse slot, mesmo que, de outra forma, ele exigisse adesão explícita. plugins.deny e plugins.entries.<id>.enabled: false ainda o bloqueiam.
• Plugins integrados de adesão explícita podem ser ativados automaticamente quando a configuração menciona uma de suas interfaces, como uma referência de provedor/modelo, configuração de canal, backend da CLI ou runtime de estrutura de agentes.
• O roteamento do Codex da família OpenAI mantém separados os limites do plugin de provedor e de runtime: referências legadas de modelos do Codex são configurações legadas que o doctor corrige, enquanto o plugin integrado codex controla o runtime do servidor de aplicativos do Codex para referências canônicas de agentes openai/*, agentRuntime.id: "codex" explícitas e referências legadas codex/*.

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

Execute openclaw doctor ou openclaw doctor --fix quando a validação da configuração informar ids de plugins obsoletos, incompatibilidades entre a lista de permissões e as ferramentas ou caminhos legados de plugins integrados.

Entender os formatos de plugins

O OpenClaw reconhece dois formatos de plugins:

Ambos os formatos aparecem em openclaw plugins list, openclaw plugins inspect, openclaw plugins enable e openclaw plugins disable. Consulte Pacotes de plugins para conhecer o limite de compatibilidade dos pacotes e Criação de plugins para criar plugins nativos.

Hooks de plugins

Os plugins podem registrar hooks no runtime por meio de duas APIs diferentes:

• api.on(...) hooks tipados para eventos do ciclo de vida do runtime. Essa é a interface preferencial para middleware, política, reescrita de mensagens, definição de prompts e controle de ferramentas.
• api.registerHook(...) para o sistema interno de hooks descrito em Hooks. Ele é usado principalmente para efeitos colaterais amplos de comandos/ciclo de vida e compatibilidade com automações existentes no estilo HOOK.

Regra rápida: se o manipulador precisar de prioridade, semântica de mesclagem ou comportamento de bloqueio/cancelamento, use hooks tipados. Se ele apenas reagir a command:new, command:reset, message:sent ou eventos amplos semelhantes, api.registerHook é suficiente.

Hooks internos gerenciados por plugins aparecem em openclaw hooks list com plugin:<id>. Não é possível 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 o estado frio da configuração, do manifesto e do registro. Eles não comprovam que um Gateway já em execução tenha importado o mesmo código do plugin.

Quando um plugin parece instalado, mas o tráfego de chat ao vivo não o utiliza:

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 modificam o código-fonte do plugin. Em instalações em VPS ou contêineres, certifique-se de que qualquer reinicialização manual tenha como alvo o processo filho openclaw gateway run real que atende aos seus canais, e não apenas um wrapper ou supervisor.

Solução de problemas

Quando uma configuração obsoleta de plugin ainda menciona um plugin de canal que não pode mais ser descoberto, a validação da configuração rebaixa essa chave de canal para um aviso em vez de uma falha grave, permitindo que a inicialização do Gateway continue atendendo a todos os outros canais. Execute openclaw doctor --fix para remover entradas obsoletas de plugins e canais. Chaves de canal desconhecidas sem evidências de plugin obsoleto ainda causam falha na validação, para que erros de digitação permaneçam visíveis.

Para uma substituição intencional de canal, o plugin preferencial 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 canais/ferramentas duplicados, em vez de escolher silenciosamente um proprietário.

Se um pacote instalado informar que requires compiled runtime output for TypeScript entry ..., o pacote foi publicado sem os arquivos JavaScript necessários para o OpenClaw no runtime. Atualize ou reinstale depois que o publicador disponibilizar o JavaScript compilado, ou desabilite/desinstale o plugin até lá.

Propriedade bloqueada do caminho do plugin

Se os diagnósticos informarem blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) e a validação vier acompanhada de 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; corrija a propriedade do sistema de arquivos ou execute o OpenClaw como o mesmo usuário proprietário do diretório de estado.

Em instalações com Docker, a imagem oficial é executada 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, altere a propriedade da raiz gerenciada dos plugins para 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 persistente de plugins corresponda aos arquivos corrigidos.

Configuração lenta das ferramentas de plugins

Se as execuções do agente parecerem travar durante a preparação das ferramentas, habilite o registro de rastreamento e procure linhas de temporização das fábricas de ferramentas de plugins:

openclaw config set logging.level traceopenclaw logs --follow

Procure por:

[trace:plugin-tools] temporizações das fábricas ...

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

O OpenClaw armazena em cache os resultados bem-sucedidos das fábricas de ferramentas de plugins para resoluções repetidas com o mesmo contexto efetivo de solicitação. A chave do cache inclui a configuração efetiva do runtime, o workspace e o id do agente, a política do sandbox, as configurações do navegador, o contexto de entrega, a identidade do solicitante e o estado de propriedade; assim, as fábricas que dependem desses campos confiáveis são executadas novamente quando o contexto muda. Se as temporizações continuarem altas, o plugin pode estar realizando trabalho dispendioso 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

Em seguida, atualize, reinstale ou desabilite esse plugin. Autores de plugins devem adiar o carregamento de dependências dispendiosas para o caminho de execução da ferramenta, em vez de realizá-lo dentro da fábrica de ferramentas.

Para informações sobre raízes de dependências, validação de metadados de pacotes, registros do registro, comportamento de recarregamento na inicialização e limpeza de itens legados, 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 integrados e externos
• Referência de plugins - páginas de referência geradas para cada 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 do registro e limites do runtime
• Criação de plugins - guia de criação de plugins nativos
• Visão geral do SDK de plugins - registro de runtime, hooks e campos da API
• Manifesto de plugin - manifesto e metadados do pacote