Configuração e ajustes 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 informe 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 contém metadados leves do pacote para descoberta de canais e superfícies de configuração antes do carregamento do runtime.

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

openclaw.install

openclaw.install contém metadados do pacote, não metadados do manifesto.

{  "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 pelo 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 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 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.

{  "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 channels (e, para plugins de provedor, adicione providers):

{  "id": "my-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  }}

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 package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

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

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

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.

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

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:

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

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:

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

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:

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

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

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:

 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),        };      },    },  ],};

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.

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-os na árvore do espaço de trabalho de plugins incluídos; eles são descobertos automaticamente durante a compilação.

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

• 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 — definePluginEntry e defineChannelPluginEntry