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 são metadados leves 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 oferece suporte a:

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

# openclaw.install

openclaw.install são metadados de pacote, não metadados 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 habilitado, o OpenClaw carrega apenas setupEntry durante a fase de inicialização pré-listen, mesmo para canais já configurados. A entrada completa carrega depois que o gateway começa a escutar.

Se sua entrada de setup/completa registra métodos RPC de gateway, mantenha-os em um prefixo específico do plugin. Namespaces administrativos centrais reservados (config.*, exec.approvals.*, wizard.*, update.*) continuam pertencendo ao core 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 schema. Um schema vazio é válido:

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

Consulte Manifesto de plugin para a referência completa do schema.

# Publicação no ClawHub

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

clawhub package publish your-org/your-plugin --dry-run
clawhub 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 (integração, 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 configuração.

Canais do workspace incluídos que mantêm exportações seguras para configuração em módulos auxiliares podem usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract em vez de defineSetupPluginEntry(...). Esse contrato incluído também oferece suporte a uma exportação runtime opcional para que a ligação de runtime no momento da configuração permaneça leve e explícita.

# Importações restritas de helpers de configuração

Para caminhos de configuração rápida, somente de configuração, prefira os seams restritos de helpers de configuração ao guarda-chuva mais amplo plugin-sdk/setup quando precisar apenas de parte da superfície de configuração:

Use o seam mais amplo plugin-sdk/setup quando quiser o conjunto completo de ferramentas compartilhadas de configuração, incluindo helpers de patch de configuração como moveSingleAccountChannelSectionToDefaultAccount(...).

Os adaptadores de patch de configuração permanecem seguros para hot-path na importação. A consulta incluída de superfície de contrato de promoção de conta única é lazy, portanto importar plugin-sdk/setup-runtime não carrega antecipadamente a descoberta de superfície de contrato incluída antes que o adaptador seja realmente usado.

# Promoção de conta única controlada pelo canal

Quando um canal é atualizado 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 incluídos podem restringir ou substituir essa promoção por meio da superfície de contrato de configuração:

• singleAccountKeysToMove: chaves extras 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(...): escolhe 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:

{
  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 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 cold-path 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 de configuração interativos 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. Veja os pacotes de Plugin incluídos (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 e então 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 sob a árvore de áreas de trabalho de Plugins integrados e eles serão descobertos automaticamente durante a compilação.

Usuários podem instalar:

openclaw plugins install <package-name>

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

# Relacionado

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