Plugins

Plugins ampliam o OpenClaw com novos recursos: canais, provedores de modelo, harnesses de agentes, ferramentas, Skills, fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagens, geração de vídeos, busca de conteúdo na web, pesquisa na web e muito mais. Alguns plugins são centrais (incluídos com o OpenClaw), outros são externos. A maioria dos plugins externos é publicada e descoberta por meio do ClawHub. O npm continua sendo compatível para instalações diretas e para um conjunto temporário de pacotes de plugins mantidos pelo OpenClaw enquanto essa migração é concluída.

Início rápido

Para exemplos de instalar, listar, desinstalar, atualizar e publicar que podem ser copiados e colados, consulte Gerenciar plugins.

openclaw plugins list

# Search ClawHub pluginsopenclaw plugins search "calendar" # From ClawHubopenclaw plugins install clawhub:openclaw-codex-app-server # From npmopenclaw plugins install npm:@acme/openclaw-pluginopenclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz # From gitopenclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0 # From a local directory or archiveopenclaw plugins install ./my-pluginopenclaw plugins install ./my-plugin.tgz

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json # If the plugin registered a CLI root, run one command from that root.openclaw <plugin-command> --help

Se preferir controle nativo do chat, habilite commands.plugins: true e use:

/plugin install clawhub:<package>/plugin show <plugin-id>/plugin enable <plugin-id>

O caminho de instalação usa o mesmo resolvedor da CLI: caminho/arquivo local, clawhub:<pkg> explícito, npm:<pkg> explícito, npm-pack:<path.tgz> explícito, git:<repo> explícito ou especificação de pacote sem prefixo via npm.

Se a configuração for inválida, a instalação normalmente falha de forma fechada e direciona você para openclaw doctor --fix. A única exceção de recuperação é um caminho estreito de reinstalação de plugin incluído para plugins que optam por openclaw.install.allowInvalidConfigRecovery. Durante a inicialização do Gateway, configuração de plugin inválida falha de forma fechada como qualquer outra configuração inválida. Execute openclaw doctor --fix para colocar em quarentena a configuração de plugin problemática, desabilitando essa entrada de plugin e removendo seu payload de configuração inválido; o backup normal de configuração mantém os valores anteriores. Quando uma configuração de canal referencia um plugin que não é mais descobrível, mas o mesmo id de plugin obsoleto permanece na configuração do plugin ou nos registros de instalação, a inicialização do Gateway registra avisos e ignora esse canal em vez de bloquear todos os outros canais. Execute openclaw doctor --fix para remover as entradas obsoletas de canal/plugin; chaves de canal desconhecidas sem evidência de plugin obsoleto ainda falham na validação para que erros de digitação continuem visíveis. Se plugins.enabled: false estiver definido, referências obsoletas de plugin são tratadas como inertes: a inicialização do Gateway ignora o trabalho de descoberta /carregamento de plugins e openclaw doctor preserva a configuração de plugins desabilitada em vez de removê-la automaticamente. Reabilite plugins antes de executar a limpeza do doctor se quiser remover ids de plugins obsoletos.

A instalação de dependências de plugin acontece apenas durante fluxos explícitos de instalação/atualização ou reparo pelo doctor. Inicialização do Gateway, recarga de configuração e inspeção de runtime não executam gerenciadores de pacotes nem reparam árvores de dependências. Plugins locais já devem ter suas dependências instaladas, enquanto plugins de npm, git e ClawHub são instalados sob as raízes de plugins gerenciadas pelo OpenClaw. Dependências npm podem ser elevadas dentro da raiz npm gerenciada pelo OpenClaw; a instalação/atualização varre essa raiz gerenciada antes da confiança, e a desinstalação remove pacotes gerenciados por npm por meio do npm. Plugins externos e caminhos de carregamento personalizados ainda devem ser instalados por meio de openclaw plugins install. Use openclaw plugins list --json para ver o dependencyStatus estático de cada plugin visível sem importar código de runtime nem reparar dependências. Consulte Resolução de dependências de plugin para o ciclo de vida em tempo de instalação.

Propriedade de caminho de plugin bloqueado

Se os diagnósticos do plugin disserem blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) e a validação da configuração vier em seguida com plugin present but blocked, o OpenClaw encontrou arquivos de plugin pertencentes a um usuário Unix diferente do processo que os está carregando. Mantenha a configuração do plugin no lugar; corrija a propriedade no 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 roda como node (uid 1000), então 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ê executa intencionalmente o OpenClaw como root, repare 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 reparados.

Para instalações npm, seletores mutáveis como latest ou uma dist-tag são resolvidos antes da instalação e então fixados na versão exata verificada na raiz npm gerenciada pelo OpenClaw. Depois que o npm termina, o OpenClaw verifica se a entrada instalada de package-lock.json ainda corresponde à versão resolvida e à integridade. Se o npm gravar metadados de pacote diferentes, a instalação falha e o pacote gerenciado é revertido em vez de aceitar um artefato de plugin diferente. Raízes npm gerenciadas também herdam os overrides npm em nível de pacote do OpenClaw, portanto pins de segurança que protegem o host empacotado também se aplicam a dependências externas de plugin elevadas.

Checkouts de origem são workspaces pnpm. Se você clonar o OpenClaw para trabalhar em plugins incluídos, execute pnpm install; então o OpenClaw carrega plugins incluídos de extensions/<id> para que edições e dependências locais do pacote sejam usadas diretamente. Instalações npm simples na raiz são para OpenClaw empacotado, não para desenvolvimento em checkout de origem.

Tipos de plugin

O OpenClaw reconhece dois formatos de plugin:

Ambos aparecem em openclaw plugins list. Consulte Bundles de plugin para detalhes sobre bundles.

Se você está escrevendo um plugin nativo, comece por Criando plugins e pela Visão geral do SDK de plugins.

Pontos de entrada de pacote

Pacotes npm de plugin nativo devem declarar openclaw.extensions em package.json. Cada entrada deve permanecer dentro do diretório do pacote e resolver para um arquivo de runtime legível, ou para um arquivo-fonte TypeScript com um par JavaScript compilado inferido, como src/index.ts para dist/index.js. Instalações empacotadas devem incluir essa saída de runtime JavaScript. O fallback de fonte TypeScript é para checkouts de origem e caminhos de desenvolvimento local, não para pacotes npm instalados na raiz de plugins gerenciada pelo OpenClaw.

Diretórios não rastreados colocados na raiz global de extensões são tratados como checkouts de origem locais e podem carregar entradas TypeScript diretamente. Diretórios ainda nomeados por um registro de instalação, incluindo installPath ou sourcePath, permanecem gerenciados e mantêm o requisito de saída compilada mesmo quando a varredura global os vê. Se você converter intencionalmente uma instalação gerenciada em um checkout local não rastreado, remova primeiro o registro de instalação obsoleto com desinstalação ou limpeza pelo doctor.

Se um aviso de pacote gerenciado disser que ele requires compiled runtime output for TypeScript entry ..., o pacote foi publicado sem os arquivos JavaScript de que o OpenClaw precisa em runtime. Isso é um problema de empacotamento do plugin, não um problema de configuração local. Atualize ou reinstale o plugin depois que o publicador republicar JavaScript compilado, ou desabilite/desinstale esse plugin até que um pacote corrigido esteja disponível.

Use openclaw.runtimeExtensions quando os arquivos de runtime publicados não ficarem nos mesmos caminhos das entradas de origem. Quando presente, runtimeExtensions deve conter exatamente uma entrada para cada entrada de extensions. Listas incompatíveis falham na instalação e na descoberta de plugins em vez de voltar silenciosamente para caminhos de origem. Se você também publicar openclaw.setupEntry, use openclaw.runtimeSetupEntry para seu par JavaScript compilado; esse arquivo é obrigatório quando declarado.

{  "name": "@acme/openclaw-plugin",  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"]  }}

Plugins oficiais

Pacotes npm mantidos pelo OpenClaw durante a migração

ClawHub é o principal caminho de distribuição para a maioria dos plugins. As versões empacotadas atuais do OpenClaw já incluem muitos plugins oficiais, então eles não precisam de instalações npm separadas em configurações normais. Até que todo plugin mantido pelo OpenClaw tenha migrado para o ClawHub, o OpenClaw ainda distribui alguns pacotes de plugin @openclaw/* no npm para instalações antigas/personalizadas e fluxos de trabalho npm diretos.

Se o npm reportar um pacote de plugin @openclaw/* como obsoleto, essa versão do pacote vem de uma linha de pacotes externos mais antiga. Use o plugin incluído na versão atual do OpenClaw ou um checkout local até que um pacote npm mais novo seja publicado.

Centrais (incluídos com o OpenClaw)

Procurando Plugins de terceiros? Consulte ClawHub.

Configuração

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

plugins.allow é exclusivo. Quando não está vazio, somente Plugins listados podem ser carregados ou expor ferramentas, mesmo que tools.allow contenha "*" ou um nome de ferramenta pertencente a um Plugin específico. Se uma lista de permissões de ferramentas referenciar ferramentas de Plugins, adicione os ids dos Plugins proprietários a plugins.allow ou remova plugins.allow; openclaw doctor avisa sobre esse formato.

plugins.bundledDiscovery usa "allowlist" por padrão para novas configurações, então um inventário restritivo de plugins.allow também bloqueia Plugins de provedores integrados omitidos, incluindo a descoberta de provedores de pesquisa na web em runtime. O Doctor marca configurações antigas com listas de permissões restritivas com "compat" durante a migração para que upgrades mantenham o comportamento legado de provedores integrados até que o operador opte pelo modo mais rigoroso. Um plugins.allow vazio ainda é tratado como não definido/aberto.

Alterações de configuração feitas por meio de /plugins enable ou /plugins disable acionam uma recarga de Plugins do Gateway em processo. Novos turnos de agente recriam sua lista de ferramentas a partir do registro de Plugins atualizado. Operações que alteram o código-fonte, como instalar, atualizar e desinstalar, ainda reiniciam o processo do Gateway porque módulos de Plugin já importados não podem ser substituídos com segurança no local.

openclaw plugins list é um snapshot local do registro/configuração de Plugins. Um Plugin enabled ali significa que o registro persistido e a configuração atual permitem que o Plugin participe. Isso não prova que um Gateway remoto já em execução foi recarregado ou reiniciado com o mesmo código de Plugin. Em configurações de VPS/contêiner com processos wrapper, envie reinícios ou escritas que acionem recarga para o processo real openclaw gateway run, ou use openclaw gateway restart contra o Gateway em execução quando a recarga relatar uma falha.

Descoberta e precedência

O OpenClaw procura Plugins nesta ordem (a primeira correspondência prevalece):

Instalações empacotadas e imagens Docker normalmente resolvem Plugins integrados a partir da árvore compilada dist/extensions. Se um diretório de código-fonte de Plugin integrado for montado por bind sobre o caminho correspondente do código-fonte empacotado, por exemplo /app/extensions/synology-chat, o OpenClaw trata esse diretório de código-fonte montado como uma sobreposição de código-fonte integrado e o descobre antes do bundle empacotado /app/dist/extensions/synology-chat. Isso mantém os loops de contêiner de mantenedores funcionando sem alternar todo Plugin integrado de volta para código-fonte TypeScript. Defina OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 para forçar bundles dist empacotados mesmo quando montagens de sobreposição de código-fonte estiverem presentes.

Regras de habilitação

• plugins.enabled: false desabilita todos os Plugins e ignora o trabalho de descoberta/carregamento de Plugins
• plugins.deny sempre prevalece sobre allow
• plugins.entries.\<id\>.enabled: false desabilita esse Plugin
• Plugins originados do workspace são desabilitados por padrão (devem ser habilitados explicitamente)
• Plugins integrados seguem o conjunto interno habilitado por padrão, a menos que sejam sobrescritos
• Slots exclusivos podem forçar a habilitação do Plugin selecionado para esse slot
• Alguns Plugins integrados opt-in são habilitados automaticamente quando a configuração nomeia uma superfície pertencente ao Plugin, como uma referência de modelo de provedor, configuração de canal ou runtime de harness
• Configuração de Plugin obsoleta é preservada enquanto plugins.enabled: false está ativo; reabilite Plugins antes de executar a limpeza do Doctor se quiser que ids obsoletos sejam removidos
• Rotas Codex da família OpenAI mantêm limites de Plugin separados: openai-codex/* pertence ao Plugin OpenAI, enquanto o Plugin app-server Codex integrado é selecionado por refs canônicas de agente openai/*, agentRuntime.id: "codex" explícito de provedor/modelo, ou refs de modelo legadas codex/*

Solução de problemas de hooks em runtime

Se um Plugin aparecer em plugins list, mas efeitos colaterais ou hooks de register(api) não forem executados no tráfego de chat ao vivo, verifique primeiro o seguinte:

• Execute openclaw gateway status --deep --require-rpc e confirme se a URL, o perfil, o caminho de configuração e o processo do Gateway ativo são os que você está editando.
• Reinicie o Gateway ao vivo após alterações de instalação/configuração/código do Plugin. Em contêineres com wrappers, o PID 1 pode ser apenas um supervisor; reinicie ou sinalize o processo filho openclaw gateway run.
• Use openclaw plugins inspect <id> --runtime --json para confirmar registros de hooks e diagnósticos. Hooks de conversa não integrados, como before_model_resolve, before_agent_reply, before_agent_run, llm_input, llm_output, before_agent_finalize e agent_end precisam de plugins.entries.<id>.hooks.allowConversationAccess=true.
• Para troca de modelo, prefira before_model_resolve. Ele é executado antes da resolução de modelo para turnos de agente; llm_output só é executado depois que uma tentativa de modelo produz saída do assistente.
• Para provar o modelo efetivo da sessão, use openclaw sessions ou as superfícies de sessão/status do Gateway e, ao depurar payloads de provedores, inicie o Gateway com --raw-stream --raw-stream-path <path>.

Configuração lenta de ferramentas de Plugin

Se os turnos de agente parecerem travar enquanto preparam ferramentas, habilite o registro de trace e verifique linhas de temporização de fábricas 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 da fábrica e as fábricas de ferramentas de Plugin mais lentas, incluindo id do Plugin, nomes declarados das ferramentas, 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 a preparação total das fábricas de ferramentas de Plugin leva pelo menos 5s.

O OpenClaw armazena em cache resultados bem-sucedidos de fábricas de ferramentas de Plugin para resoluções repetidas com o mesmo contexto efetivo de requisição. A chave de cache inclui a configuração efetiva de runtime, workspace, ids de agente/sessão, política de sandbox, configurações de navegador, contexto de entrega, identidade do solicitante e estado de propriedade, então fábricas que dependem desses campos confiáveis são reexecutadas quando o contexto muda.

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 mover o carregamento caro de dependências para trás do caminho de execução da ferramenta, em vez de fazê-lo dentro da fábrica da ferramenta.

Propriedade duplicada de canal ou ferramenta

Sintomas:

• channel already registered: <channel-id> (<plugin-id>)
• channel setup already registered: <channel-id> (<plugin-id>)
• plugin tool name conflict (<plugin-id>): <tool-name>

Isso significa que mais de um Plugin habilitado está tentando possuir o mesmo canal, fluxo de configuração ou nome de ferramenta. A causa mais comum é um Plugin de canal externo instalado ao lado de um Plugin integrado que agora fornece o mesmo id de canal.

Etapas de depuração:

• Execute openclaw plugins list --enabled --verbose para ver todos os Plugins habilitados e suas origens.
• Execute openclaw plugins inspect <id> --runtime --json para cada Plugin suspeito e compare channels, channelConfigs, tools e diagnósticos.
• Execute openclaw plugins registry --refresh após instalar ou remover pacotes de Plugin para que os metadados persistidos reflitam a instalação atual.
• Reinicie o Gateway após alterações de instalação, registro ou configuração.

Opções de correção:

• Se um Plugin substituir intencionalmente outro para o mesmo id de canal, o Plugin preferido deve declarar channelConfigs.<channel-id>.preferOver com o id do Plugin de prioridade mais baixa. Consulte /plugins/manifest#replacing-another-channel-plugin.
• Se a duplicata for acidental, desabilite um lado com plugins.entries.<plugin-id>.enabled: false ou remova a instalação obsoleta do Plugin.
• Se você habilitou explicitamente ambos os Plugins, o OpenClaw mantém essa solicitação e relata o conflito. Escolha um proprietário para o canal ou renomeie as ferramentas pertencentes ao Plugin para que a superfície de runtime seja inequívoca.

Slots de Plugin (categorias exclusivas)

Algumas categorias são exclusivas (somente uma ativa por vez):

{  plugins: {    slots: {      memory: "memory-core", // or "none" to disable      contextEngine: "legacy", // or a plugin id    },  },}

Referência da CLI

openclaw plugins list                       # compact inventoryopenclaw plugins list --enabled            # only enabled pluginsopenclaw plugins list --verbose            # per-plugin detail linesopenclaw plugins list --json               # machine-readable inventoryopenclaw plugins search <query>            # search ClawHub plugin catalogopenclaw plugins inspect <id>              # static detailopenclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methodsopenclaw plugins inspect <id> --json       # machine-readableopenclaw plugins inspect --all             # fleet-wide tableopenclaw plugins info <id>                 # inspect aliasopenclaw plugins doctor                    # diagnosticsopenclaw plugins registry                  # inspect persisted registry stateopenclaw plugins registry --refresh        # rebuild persisted registryopenclaw doctor --fix                      # repair plugin registry state openclaw plugins install <package>         # install from npm by defaultopenclaw plugins install clawhub:<pkg>     # install from ClawHub onlyopenclaw plugins install npm:<pkg>         # install from npm onlyopenclaw plugins install git:<repo>        # install from gitopenclaw plugins install git:<repo>@<ref>  # install from git refopenclaw plugins install <spec> --force    # overwrite existing installopenclaw plugins install <path>            # install from local pathopenclaw plugins install -l <path>         # link (no copy) for devopenclaw plugins install <plugin> --marketplace <source>openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <spec> --pin      # record exact resolved npm specopenclaw plugins install <spec> --dangerously-force-unsafe-installopenclaw plugins update <id-or-npm-spec> # update one pluginopenclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-installopenclaw plugins update --all            # update allopenclaw plugins uninstall <id>          # remove config and plugin index recordsopenclaw plugins uninstall <id> --keep-filesopenclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --json # Verify runtime registrations after install.openclaw plugins inspect <id> --runtime --json # Run plugin-owned CLI commands directly from the OpenClaw root CLI.openclaw <plugin-command> --help openclaw plugins enable <id>openclaw plugins disable <id>

Plugins incluídos são distribuídos com o OpenClaw. Muitos são habilitados por padrão (por exemplo, provedores de modelo incluídos, provedores de fala incluídos e o plugin de navegador incluído). Outros plugins incluídos ainda precisam de openclaw plugins enable <id>.

--force sobrescreve no local um plugin instalado ou pacote de hooks existente. Use openclaw plugins update <id-or-npm-spec> para atualizações de rotina de plugins npm rastreados. Ele não é compatível com --link, que reutiliza o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.

Quando plugins.allow já está definido, openclaw plugins install adiciona o id do plugin instalado a essa lista de permissões antes de habilitá-lo. Se o mesmo id de plugin estiver presente em plugins.deny, a instalação remove essa entrada de negação obsoleta para que a instalação explícita possa ser carregada imediatamente após a reinicialização.

O OpenClaw mantém um registro local persistente de plugins como o modelo de leitura fria para inventário de plugins, propriedade de contribuições e planejamento de inicialização. Os fluxos de instalação, atualização, desinstalação, habilitação e desabilitação atualizam esse registro após alterar o estado do plugin. O mesmo arquivo plugins/installs.json mantém metadados duráveis de instalação em installRecords no nível superior e metadados de manifesto reconstruíveis em plugins. Se o registro estiver ausente, obsoleto ou inválido, openclaw plugins registry --refresh reconstrói sua visualização de manifesto a partir dos registros de instalação, política de configuração e metadados de manifesto/pacote sem carregar módulos de runtime de plugin.

No modo Nix (OPENCLAW_NIX_MODE=1), os mutadores de ciclo de vida de plugin ficam desabilitados. Gerencie a seleção de pacotes de plugin e a configuração por meio da origem Nix da instalação; para nix-openclaw, comece pelo Guia de início rápido centrado no agente. openclaw plugins update <id-or-npm-spec> se aplica a instalações rastreadas. Passar uma especificação de pacote npm com uma dist-tag ou versão exata resolve o nome do pacote de volta para o registro de plugin rastreado e registra a nova especificação para atualizações futuras. Passar o nome do pacote sem uma versão move uma instalação fixada exata de volta para a linha de lançamento padrão do registro. Se o plugin npm instalado já corresponder à versão resolvida e à identidade de artefato registrada, o OpenClaw ignora a atualização sem baixar, reinstalar ou reescrever a configuração. Quando openclaw update é executado no canal beta, registros de plugin npm e ClawHub na linha padrão tentam @beta primeiro e recorrem a default/latest quando não existe lançamento beta do plugin. Versões exatas e tags explícitas permanecem fixadas.

--pin é exclusivo para npm. Ele não é compatível com --marketplace, porque instalações de marketplace persistem metadados da origem do marketplace em vez de uma especificação npm.

--dangerously-force-unsafe-install é uma substituição de emergência para falsos positivos do scanner integrado de código perigoso. Ela permite que instalações de plugins e atualizações de plugins prossigam apesar de achados critical integrados, mas ainda não contorna bloqueios de política before_install de plugins nem bloqueios por falha de verificação. As verificações de instalação ignoram arquivos e diretórios comuns de teste, como tests/, __tests__/, *.test.* e *.spec.*, para evitar bloquear mocks de teste empacotados; entrypoints de runtime de plugin declarados ainda são verificados mesmo que usem um desses nomes.

Essa flag de CLI se aplica apenas aos 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 continua sendo o fluxo separado de download/instalação de Skills do ClawHub.

Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma verificação, abra o painel do ClawHub ou execute clawhub package rescan <name> para pedir que o ClawHub o verifique novamente. --dangerously-force-unsafe-install afeta apenas instalações na sua própria máquina; ela não pede que o ClawHub verifique novamente o plugin nem torna público um lançamento bloqueado.

Bundles compatíveis participam do mesmo fluxo de listar/inspecionar/habilitar/desabilitar plugins. O suporte atual de runtime inclui Skills de bundle, command-skills do Claude, padrões de settings.json do Claude, padrões de lspServers declarados por manifesto e .lsp.json do Claude, command-skills do Cursor e diretórios de hooks compatíveis do Codex.

openclaw plugins inspect <id> também relata capacidades de bundle detectadas, além de entradas de servidor MCP e LSP compatíveis ou incompatíveis para plugins apoiados por bundle.

Origens de marketplace podem ser um nome de marketplace conhecido do Claude em ~/.claude/plugins/known_marketplaces.json, uma raiz local de marketplace ou caminho marketplace.json, uma abreviação do GitHub como owner/repo, uma URL de repositório do GitHub ou uma URL git. Para marketplaces remotos, as entradas de plugin devem permanecer dentro do repositório de marketplace clonado e usar apenas origens de caminho relativo.

Consulte a referência da CLI openclaw plugins para todos os detalhes.

Visão geral da API de Plugin

Plugins nativos exportam um objeto de entrada que expõe register(api). Plugins mais antigos ainda podem usar activate(api) como um alias legado, mas plugins novos devem usar register.

export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });    api.registerChannel({      /* ... */    });  },});

O OpenClaw carrega o objeto de entrada e chama register(api) durante a ativação do plugin. O carregador ainda recorre a activate(api) para plugins mais antigos, mas plugins incluídos e novos plugins externos devem tratar register como o contrato público.

api.registrationMode informa a um plugin por que sua entrada está sendo carregada:

Entradas de plugin que abrem sockets, bancos de dados, workers em segundo plano ou clientes de longa duração devem proteger esses efeitos colaterais com api.registrationMode === "full". Carregamentos de descoberta são armazenados em cache separadamente dos carregamentos de ativação e não substituem o registro em execução do Gateway. A descoberta não ativa, mas não é livre de import: o OpenClaw pode avaliar a entrada de plugin confiável ou o módulo de plugin de canal para construir o snapshot. Mantenha os níveis superiores dos módulos leves e sem efeitos colaterais, e mova clientes de rede, subprocessos, listeners, leituras de credenciais e inicialização de serviços para trás de caminhos de runtime completo.

Métodos comuns de registro:

Comportamento de proteção de hooks para hooks tipados de ciclo de vida:

• before_tool_call: { block: true } é terminal; handlers de menor prioridade são ignorados.
• before_tool_call: { block: false } não tem efeito e não limpa um bloqueio anterior.
• before_install: { block: true } é terminal; handlers de menor prioridade são ignorados.
• before_install: { block: false } não tem efeito e não limpa um bloqueio anterior.
• message_sending: { cancel: true } é terminal; handlers de menor prioridade são ignorados.
• message_sending: { cancel: false } não tem efeito e não limpa um cancelamento anterior.

O app-server nativo do Codex encaminha eventos de ferramentas nativas do Codex de volta para esta superfície de hooks. Plugins podem bloquear ferramentas nativas do Codex por meio de before_tool_call, observar resultados por meio de after_tool_call e participar das aprovações PermissionRequest do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do Codex. O limite exato de suporte do runtime do Codex está no contrato de suporte v1 do harness do Codex.

Para o comportamento completo de hooks tipados, consulte a visão geral do SDK.

Relacionados

• Como criar plugins - crie seu próprio plugin
• Pacotes de plugins - compatibilidade de pacotes Codex/Claude/Cursor
• Manifesto do Plugin - esquema do manifesto
• Registro de ferramentas - adicione ferramentas de agente em um plugin
• Componentes internos do Plugin - modelo de capacidades e pipeline de carregamento
• ClawHub - descoberta de plugins de terceiros