Skip to main content
Referência para empacotamento de plugins (metadados de package.json), manifestos (openclaw.plugin.json), entradas de configuração e esquemas de configuração.
Procurando um passo a passo? Os guias práticos abordam o empacotamento em contexto: Plugins de canal e Plugins de provedor.

Metadados do pacote

Seu package.json precisa de um campo openclaw que informe ao sistema de plugins o que seu plugin fornece:
A publicação externa no ClawHub exige compat e build. Os trechos canônicos de publicação ficam em docs/snippets/plugin-publish/.

Campos de openclaw

string[]
Arquivos de ponto de entrada (relativos à raiz do pacote). Entradas de código-fonte válidas para desenvolvimento no workspace e em checkouts do git.
string[]
Arquivos JavaScript compilados correspondentes a extensions, preferidos quando o OpenClaw carrega um pacote npm instalado. Consulte Pontos de entrada do SDK para ver a ordem de resolução entre código-fonte e código compilado.
string
Entrada leve usada apenas para configuração (opcional).
string
Arquivo JavaScript compilado correspondente a setupEntry. Exige que setupEntry também esteja definido.
object
Identidade alternativa do plugin no formato { id, label }, usada quando um plugin não tem metadados de canal/provedor dos quais derivar um id ou rótulo.
object
Metadados do catálogo de canais para superfícies de configuração, seleção, início rápido e status.
object
Indicações de instalação: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery, requiredPlatformPackages.
object
Sinalizadores de comportamento de inicialização.
object
Intervalo de versões de pluginApi compatível com este plugin. Obrigatório para publicações externas no ClawHub.
Os ids de provedores (providers: string[]) são metadados do manifesto, não metadados do pacote. Declare-os em openclaw.plugin.json, não aqui — consulte Manifesto do plugin.

openclaw.channel

openclaw.channel contém metadados leves do pacote para descoberta de canais e superfícies de configuração antes do carregamento do runtime. Exemplo:
exposure aceita:
  • configured: inclui o canal em superfícies de listagem de canais configurados/status
  • setup: inclui o canal nos seletores interativos de configuração
  • docs: marca o canal como público nas superfícies de documentação/navegação
showConfigured e showInSetup continuam disponíveis como aliases legados. Prefira exposure.

openclaw.install

openclaw.install contém metadados do pacote, não metadados do manifesto.
A integração inicial interativa usa openclaw.install para superfícies de instalação sob demanda: se seu plugin expõe opções de autenticação de provedor ou metadados de configuração/catálogo de canais antes do carregamento do runtime, a integração inicial pode solicitar uma instalação pelo ClawHub, npm ou local, instalar ou habilitar o plugin e então continuar o fluxo selecionado. As opções do ClawHub usam clawhubSpec e são preferidas quando presentes; as opções do npm exigem metadados confiáveis de catálogo com um npmSpec do registro (versões exatas e expectedIntegrity são fixações opcionais, aplicadas na instalação/atualização quando definidas). Mantenha “o que exibir” em openclaw.plugin.json e “como instalar” em package.json.
Se minHostVersion estiver definido, tanto a instalação quanto o carregamento pelo registro de manifestos não incluídos o aplicarão. Hosts mais antigos ignoram plugins externos; strings de versão inválidas são rejeitadas. Presume-se que plugins de código-fonte incluídos tenham a mesma versão do checkout do host.
Para instalações npm fixadas, mantenha a versão exata em npmSpec e adicione a integridade esperada do artefato:
allowInvalidConfigRecovery não é um mecanismo geral para ignorar configurações inválidas. Ele se destina apenas à recuperação restrita de plugins incluídos, permitindo que a reinstalação/configuração corrija resíduos conhecidos de atualizações, como a ausência do caminho de um plugin incluído ou uma entrada channels.<id> obsoleta desse mesmo plugin. Se a configuração estiver inválida por motivos não relacionados, a instalação ainda falhará de forma segura e instruirá o operador a executar openclaw doctor --fix.

Carregamento completo adiado

Plugins de canal podem optar pelo carregamento adiado com:
Quando habilitado, o OpenClaw carrega apenas setupEntry durante a fase de inicialização anterior à escuta, mesmo para canais já configurados. A entrada completa é carregada depois que o Gateway começa a escutar.
Habilite o carregamento adiado somente quando seu setupEntry registrar tudo de que o Gateway precisa antes de começar a escutar (registro do canal, rotas HTTP, métodos do Gateway). Se a entrada completa for responsável por recursos obrigatórios de inicialização, mantenha o comportamento padrão.
Se sua entrada de configuração/completa registrar métodos RPC do Gateway, mantenha-os sob um prefixo específico do plugin. Os namespaces administrativos reservados do núcleo (config.*, exec.approvals.*, wizard.*, update.*) permanecem sob responsabilidade do núcleo e sempre são normalizados para operator.admin.

Manifesto do plugin

Todo plugin nativo deve incluir um openclaw.plugin.json na raiz do pacote. O OpenClaw usa esse arquivo para validar a configuração sem executar o código do plugin.
Para plugins de canal, adicione channels (e, para plugins de provedor, adicione providers):
Mesmo plugins sem configuração devem incluir um esquema. Um esquema vazio é válido:
Consulte Manifesto do plugin para ver a referência completa do esquema.

Publicação no ClawHub

Skills e pacotes de plugins usam comandos de publicação distintos no ClawHub. Para pacotes de plugins, use o comando específico para pacotes:
clawhub skill publish <path> é um comando diferente, usado para publicar uma pasta de Skill, não um pacote de plugin. Consulte Publicação no ClawHub.

Entrada de configuração

setup-entry.ts é uma alternativa leve ao index.ts, carregada pelo OpenClaw quando ele precisa apenas das superfícies de configuração inicial (integração inicial, reparo de configuração e inspeção de canais desativados):
Isso evita carregar código pesado de execução (bibliotecas criptográficas, registros da CLI e serviços em segundo plano) durante os fluxos de configuração inicial. Canais incluídos no espaço de trabalho que mantêm exportações seguras para configuração inicial em módulos auxiliares podem usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract em vez de defineSetupPluginEntry(...). Esse contrato incluído também aceita uma exportação opcional runtime, permitindo que a vinculação da execução durante a configuração permaneça leve e explícita.
  • O canal está desativado, mas precisa de superfícies de configuração inicial ou integração inicial.
  • O canal está ativado, mas não configurado.
  • O carregamento adiado está ativado (deferConfiguredChannelFullLoadUntilAfterListen).
  • O objeto do plugin de canal (por meio de defineSetupPluginEntry).
  • Todas as rotas HTTP necessárias antes de o Gateway começar a escutar.
  • Todos os métodos do Gateway necessários durante a inicialização.
Esses métodos de inicialização do Gateway ainda devem evitar namespaces administrativos reservados do núcleo, como config.* ou update.*.
  • Registros da CLI.
  • Serviços em segundo plano.
  • Importações pesadas de execução (criptografia, SDKs).
  • Métodos do Gateway necessários somente após a inicialização.

Importações específicas de auxiliares de configuração

Para caminhos críticos usados apenas na configuração inicial, prefira as interfaces específicas de auxiliares de configuração em vez da interface abrangente plugin-sdk/setup quando precisar somente de parte da superfície de configuração: Use a interface mais abrangente plugin-sdk/setup quando quiser o conjunto completo de ferramentas compartilhadas de configuração, incluindo auxiliares de alteração da configuração, como moveSingleAccountChannelSectionToDefaultAccount(...). Use createSetupTranslator(...) para textos fixos do assistente de configuração. Ele segue a localidade do assistente da CLI (OPENCLAW_LOCALE e, em seguida, as variáveis de localidade do sistema) e usa o inglês como alternativa. Mantenha o texto de configuração específico do plugin no código pertencente ao plugin e use chaves compartilhadas do catálogo somente para rótulos comuns de configuração, textos de status e textos de configuração dos plugins oficiais incluídos. Os adaptadores de alteração da configuração continuam seguros para importação em caminhos críticos. A consulta à superfície do contrato incluído de promoção de conta única é preguiçosa; portanto, importar plugin-sdk/setup-runtime não carrega antecipadamente a descoberta das superfícies de contrato incluídas antes de o adaptador ser efetivamente usado.

Promoção de conta única pertencente ao canal

Quando um canal migra de uma configuração de nível superior com uma única conta para channels.<id>.accounts.*, o comportamento compartilhado padrão move os valores promovidos com escopo de conta para accounts.default. Canais incluídos podem restringir ou substituir essa promoção por meio de sua superfície de contrato de configuração:
  • singleAccountKeysToMove: chaves adicionais de nível superior que devem ser movidas para a conta promovida
  • namedAccountPromotionKeys: quando já existem contas nomeadas, somente essas chaves são movidas para a conta promovida; as chaves compartilhadas de política e entrega permanecem na raiz do canal
  • resolveSingleAccountPromotionTarget(...): escolhe qual conta existente recebe os valores promovidos
Matrix é o exemplo incluído atual. Se já existir exatamente uma conta nomeada do Matrix, ou se defaultAccount apontar para uma chave não canônica existente, como Ops, a promoção preservará essa conta em vez de criar uma nova entrada accounts.default.

Esquema de configuração

A configuração do plugin é validada em relação ao JSON Schema do manifesto. Os usuários configuram plugins por meio de:
Seu plugin recebe essa configuração como api.pluginConfig durante o registro. Para configurações específicas do canal, use a seção de configuração do canal:

Criação de esquemas de configuração de canais

Use buildChannelConfigSchema para converter um esquema Zod no invólucro ChannelConfigSchema usado pelos artefatos de configuração pertencentes ao plugin:
Se você já define o contrato como JSON Schema ou TypeBox, use o auxiliar direto para que o OpenClaw possa ignorar a conversão de Zod para JSON Schema nos caminhos de metadados:
Para plugins de terceiros, o contrato do caminho não crítico ainda é o manifesto do plugin: replique o JSON Schema gerado em openclaw.plugin.json#channelConfigs para que as superfícies de esquema de configuração, configuração inicial e interface possam inspecionar channels.<id> sem carregar o código de execução.

Assistentes de configuração

Plugins de canal podem fornecer assistentes interativos de configuração para openclaw onboard. O assistente é um objeto ChannelSetupWizard no ChannelPlugin:
ChannelSetupWizard também aceita textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize e outros recursos. Consulte src/setup-core.ts do plugin do Discord para ver um exemplo completo incluído.
Para solicitações de lista de permissões de mensagens diretas que precisam apenas do fluxo padrão note -> prompt -> parse -> merge -> patch, prefira os auxiliares compartilhados de configuração de openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) e createNestedChannelParsedAllowFromPrompt(...).
Para blocos de status da configuração do canal que variam somente em rótulos, pontuações e linhas adicionais opcionais, prefira createStandardChannelSetupStatus(...) de openclaw/plugin-sdk/setup em vez de criar manualmente o mesmo objeto status em cada plugin.
Para superfícies opcionais de configuração que devem aparecer somente em determinados contextos, use createOptionalChannelSetupSurface de openclaw/plugin-sdk/channel-setup:
plugin-sdk/channel-setup também expõe os construtores de nível mais baixo createOptionalChannelSetupAdapter(...) e createOptionalChannelSetupWizard(...) quando você precisa apenas de uma das partes dessa superfície de instalação opcional.O adaptador/assistente opcional gerado falha de forma segura em gravações reais de configuração. Eles reutilizam uma única mensagem de instalação obrigatória em validateInput, applyAccountConfig e finalize, e acrescentam um link para a documentação quando docsPath está definido.
Para interfaces de configuração baseadas em binários, prefira os auxiliares compartilhados de delegação em vez de copiar a mesma lógica de integração de binário/status para cada canal:
  • createDetectedBinaryStatus(...) para blocos de status que variam apenas por rótulos, dicas, pontuações e detecção de binário
  • createCliPathTextInput(...) para entradas de texto baseadas em caminhos
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) e createDelegatedResolveConfigured(...) quando setupEntry precisar encaminhar de forma adiada para um assistente completo mais robusto
  • createDelegatedTextInputShouldPrompt(...) quando setupEntry precisar apenas delegar uma decisão de textInputs[*].shouldPrompt

Publicação e instalação

Plugins externos: publique no ClawHub e depois instale:
Especificações simples de pacotes são instaladas pelo npm durante a transição de inicialização, a menos que o nome corresponda ao ID de um plugin incluído ou oficial; nesse caso, o OpenClaw usa a respectiva cópia local/oficial. Use clawhub:, npm:, git: ou npm-pack: para selecionar a origem de forma determinística — consulte Gerenciar plugins.
Plugins no repositório: coloque-os na árvore do espaço de trabalho de plugins incluídos; eles são descobertos automaticamente durante a compilação.
Para instalações com origem no npm, openclaw plugins install instala o pacote em um projeto específico do plugin em ~/.openclaw/npm/projects, com os scripts de ciclo de vida desativados (--ignore-scripts). Mantenha as árvores de dependências dos plugins exclusivamente em JS/TS e evite pacotes que exijam compilações em postinstall.
A inicialização do Gateway não instala dependências de plugins. Os fluxos de instalação via npm/git/ClawHub são responsáveis pela convergência das dependências; plugins locais já devem ter suas dependências instaladas.
Os metadados dos pacotes incluídos são explícitos, não inferidos do JavaScript compilado durante a inicialização do Gateway. As dependências de tempo de execução devem estar no pacote do plugin que as possui; a inicialização do OpenClaw empacotado nunca repara nem espelha dependências de plugins.

Relacionado