Instalação e configuração do Plugin

Referência para empacotamento de plugins (metadados de package.json), manifestos (openclaw.plugin.json), entradas de configuração e esquemas de configuração.

Metadados do pacote

Seu package.json precisa de um campo openclaw que informa ao sistema de plugins o que seu plugin fornece:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Campos de openclaw

openclaw.channel

openclaw.channel é metadado barato de pacote para descoberta de canais e superfícies de configuração antes do runtime carregar.

Exemplo:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure é compatível com:

• configured: inclui o canal em superfícies de listagem configuradas/de estilo status
• setup: inclui o canal em seletores interativos de configuração
• docs: marca o canal como público em superfícies de documentação/navegação

openclaw.install

openclaw.install é metadado de pacote, não metadado de manifesto.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Carregamento completo adiado

Plugins de canal podem optar por carregamento adiado com:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Quando ativado, o OpenClaw carrega apenas setupEntry durante a fase de inicialização anterior à escuta, mesmo para canais já configurados. A entrada completa carrega depois que o Gateway começa a escutar.

Se sua entrada de configuração/completa registra métodos RPC do Gateway, mantenha-os em um prefixo específico do plugin. Namespaces administrativos centrais reservados (config.*, exec.approvals.*, wizard.*, update.*) continuam pertencendo ao núcleo e sempre resolvem para operator.admin.

Manifesto de plugin

Todo plugin nativo deve incluir um openclaw.plugin.json na raiz do pacote. O OpenClaw usa isso para validar a configuração sem executar código do plugin.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Para plugins de canal, adicione kind e channels:

{  "id": "my-channel",  "kind": "channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Mesmo plugins sem configuração devem incluir um esquema. Um esquema vazio é válido:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Veja Manifesto de plugin para a referência completa do esquema.

Publicação no ClawHub

Para pacotes de plugin, use o comando ClawHub específico do pacote:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Entrada de configuração

O arquivo setup-entry.ts é uma alternativa leve ao index.ts que o OpenClaw carrega quando precisa apenas de superfícies de configuração (onboarding, reparo de configuração, inspeção de canal desativado).

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Isso evita carregar código pesado de runtime (bibliotecas de criptografia, registros de CLI, serviços em segundo plano) durante fluxos de configuração.

Canais agrupados no workspace que mantêm exports seguros para configuração em módulos auxiliares podem usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract em vez de defineSetupPluginEntry(...). Esse contrato agrupado também aceita um export opcional runtime, para que a ligação de runtime em tempo de configuração permaneça leve e explícita.

Imports estreitos de auxiliares de configuração

Para caminhos quentes somente de configuração, prefira os pontos de integração estreitos de auxiliares de configuração em vez do guarda-chuva mais amplo plugin-sdk/setup quando você precisar apenas de parte da superfície de configuração:

Use o ponto de integração mais amplo plugin-sdk/setup quando quiser o conjunto completo compartilhado de ferramentas de configuração, incluindo auxiliares de patch de configuração como moveSingleAccountChannelSectionToDefaultAccount(...).

Os adaptadores de patch de configuração continuam seguros para caminhos quentes no import. A busca de superfície de contrato agrupada para promoção de conta única é lazy, portanto importar plugin-sdk/setup-runtime não carrega antecipadamente a descoberta de superfície de contrato agrupada antes que o adaptador seja realmente usado.

Promoção de conta única controlada pelo canal

Quando um canal faz upgrade de uma configuração de nível superior de conta única para channels.<id>.accounts.*, o comportamento compartilhado padrão é mover valores promovidos com escopo de conta para accounts.default.

Canais agrupados 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 contas nomeadas já existem, apenas essas chaves são movidas para a conta promovida; chaves compartilhadas de política/entrega permanecem na raiz do canal
• resolveSingleAccountPromotionTarget(...): escolher qual conta existente recebe os valores promovidos

Esquema de configuração

A configuração do Plugin é validada contra o JSON Schema no seu manifesto. Usuários configuram plugins via:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Seu Plugin recebe essa configuração como api.pluginConfig durante o registro.

Para configuração específica de canal, use a seção de configuração do canal em vez disso:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Criando esquemas de configuração de canal

Use buildChannelConfigSchema para converter um esquema Zod no wrapper ChannelConfigSchema usado por artefatos de configuração controlados pelo Plugin:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Se você já escreve o contrato como JSON Schema ou TypeBox, use o auxiliar direto para que o OpenClaw possa pular a conversão de Zod para JSON Schema em caminhos de metadados:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Para plugins de terceiros, o contrato de caminho frio ainda é o manifesto do Plugin: espelhe o JSON Schema gerado em openclaw.plugin.json#channelConfigs para que o esquema de configuração, a configuração e as superfícies de UI possam inspecionar channels.<id> sem carregar código de runtime.

Assistentes de configuração

Plugins de canal podem fornecer assistentes interativos de configuração para openclaw onboard. O assistente é um objeto ChannelSetupWizard em ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

O tipo ChannelSetupWizard aceita credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize e mais. Veja pacotes de Plugin agrupados (por exemplo, o Plugin do Discord src/channel.setup.ts) para exemplos completos.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Publicação e instalação

Plugins externos: publique no ClawHub, depois instale:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Plugins no repositório: coloque sob a árvore de workspace de plugins agrupados e eles serão descobertos automaticamente durante a compilação.

Usuários podem instalar:

openclaw plugins install <package-name>

Os metadados de pacotes agrupados são explícitos, não inferidos do JavaScript compilado na inicialização do Gateway. Dependências de runtime pertencem ao pacote do plugin que as possui; a inicialização do OpenClaw empacotado nunca repara nem espelha dependências de plugins.

Relacionados

• Criando plugins — guia passo a passo para começar
• Manifesto do plugin — referência completa do esquema do manifesto
• Pontos de entrada do SDK — definePluginEntry e defineChannelPluginEntry