Instalação e configuração do Plugin

Referência para empacotamento de Plugins (metadados de package.json), manifests (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",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "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 são metadados leves de pacote para descoberta de canal e superfícies de configuração antes que o tempo de execução seja carregado.

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 aceita:

• configured: inclui o canal em superfícies de listagem configuradas/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 são metadados de pacote, não metadados de manifest.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "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 habilitado, o OpenClaw carrega apenas setupEntry durante a fase de inicialização antes de escutar, 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 reservados de administração do core (config.*, exec.approvals.*, wizard.*, update.*) permanecem de propriedade do core e sempre resolvem para operator.admin.

Manifest do 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 precisam enviar um schema. Um schema vazio é válido:

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

Consulte manifesto do Plugin para a referência completa do schema.

Publicação no ClawHub

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

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

Entrada de setup

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

// 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 setup.

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

Imports estreitos de helpers de setup

Para caminhos quentes somente de setup, prefira as interfaces estreitas de helpers de setup em vez do guarda-chuva mais amplo plugin-sdk/setup quando você só precisar de parte da superfície de setup:

Use a interface mais ampla plugin-sdk/setup quando quiser a caixa de ferramentas compartilhada completa de setup, incluindo helpers de patch de configuração como moveSingleAccountChannelSectionToDefaultAccount(...).

Use createSetupTranslator(...) para textos fixos do assistente de setup. Ele segue o locale do assistente da CLI (OPENCLAW_LOCALE, depois variáveis de locale do sistema) e recua para inglês. Mantenha texto de setup específico do plugin no código pertencente ao plugin e use chaves de catálogo compartilhadas apenas para rótulos comuns de setup, texto de status e textos de setup de plugins agrupados oficiais.

Os adaptadores de patch de setup permanecem seguros para caminho quente no import. A consulta de superfície de contrato de promoção de conta única agrupada deles é preguiçosa, então importar plugin-sdk/setup-runtime não carrega avidamente a descoberta de superfície de contrato agrupada antes de o adaptador ser realmente usado.

Promoção de conta única pertencente ao 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 sobrescrever essa promoção por meio da superfície de contrato de setup deles:

• singleAccountKeysToMove: chaves extras de nível superior que devem ser movidas para a conta promovida
• namedAccountPromotionKeys: quando contas nomeadas já existem, somente estas chaves se movem para a conta promovida; chaves compartilhadas de política/entrega permanecem na raiz do canal
• resolveSingleAccountPromotionTarget(...): escolhe qual conta existente recebe os valores promovidos

Schema 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:

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

Criando schemas de configuração de canal

Use buildChannelConfigSchema para converter um schema Zod no wrapper ChannelConfigSchema usado por artefatos de configuração pertencentes ao 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á cria o contrato como JSON Schema ou TypeBox, use o helper 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 schema de configuração, setup e superfícies de UI possam inspecionar channels.<id> sem carregar código de runtime.

Assistentes de setup

Plugins de canal podem fornecer assistentes interativos de setup para openclaw onboard. O assistente é um objeto ChannelSetupWizard no 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 oferece suporte a credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize e mais. Consulte pacotes de plugins agrupados (por exemplo, o plugin 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 e 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 empacotados, e eles serão descobertos automaticamente durante o build.

Usuários podem instalar:

openclaw plugins install <package-name>

Os metadados de pacotes empacotados são explícitos, não inferidos a partir 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