package.json), manifestos (openclaw.plugin.json), entradas de configuração e esquemas de configuração.
Metadados do pacote
Seupackage.json precisa de um campo openclaw que informe ao sistema de plugins o que seu plugin fornece:
- Plugin de canal
- Plugin de provedor / linha de base do ClawHub
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/statussetup: inclui o canal nos seletores interativos de configuraçãodocs: 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.
Comportamento da integração inicial
Comportamento da integração inicial
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.Aplicação de minHostVersion
Aplicação de minHostVersion
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.Instalações npm fixadas
Instalações npm fixadas
Para instalações npm fixadas, mantenha a versão exata em
npmSpec e adicione a integridade esperada do artefato:Escopo de allowInvalidConfigRecovery
Escopo de allowInvalidConfigRecovery
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: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.
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 umopenclaw.plugin.json na raiz do pacote. O OpenClaw usa esse arquivo para validar a configuração sem executar o código do plugin.
channels (e, para plugins de provedor, adicione providers):
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):
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.
Quando o OpenClaw usa setupEntry em vez da entrada completa
Quando o OpenClaw usa setupEntry em vez da entrada completa
- 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 que setupEntry deve registrar
O que setupEntry deve registrar
- 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.
config.* ou update.*.O que setupEntry NÃO deve incluir
O que setupEntry NÃO deve incluir
- 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 abrangenteplugin-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 parachannels.<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 promovidanamedAccountPromotionKeys: 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 canalresolveSingleAccountPromotionTarget(...): 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: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
UsebuildChannelConfigSchema para converter um esquema Zod no invólucro ChannelConfigSchema usado pelos artefatos de configuração pertencentes ao plugin:
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 paraopenclaw 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.
Solicitações compartilhadas de allowFrom
Solicitações compartilhadas de allowFrom
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(...).Status padrão da configuração do canal
Status padrão da configuração do canal
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.Superfície opcional de configuração do canal
Superfície opcional de configuração do canal
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.Auxiliares de configuração baseados em binários
Auxiliares de configuração baseados em binários
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áriocreateCliPathTextInput(...)para entradas de texto baseadas em caminhoscreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)ecreateDelegatedResolveConfigured(...)quandosetupEntryprecisar encaminhar de forma adiada para um assistente completo mais robustocreateDelegatedTextInputShouldPrompt(...)quandosetupEntryprecisar apenas delegar uma decisão detextInputs[*].shouldPrompt
Publicação e instalação
Plugins externos: publique no ClawHub e depois instale:- npm
- Somente ClawHub
- Especificação de pacote npm
clawhub:, npm:, git: ou npm-pack: para selecionar a origem de forma determinística — consulte Gerenciar plugins.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.
Relacionado
- Criação de plugins — guia de introdução passo a passo
- Manifesto de plugin — referência completa do esquema do manifesto
- Pontos de entrada do SDK —
definePluginEntryedefineChannelPluginEntry