Criando plugins de canal

​

Responsabilidades do seu Plugin

• Configuração - resolução de contas e assistente de configuração
• Segurança - política de mensagens diretas e listas de permissões
• Pareamento - fluxo de aprovação de mensagens diretas
• Gramática da sessão - como os IDs de conversa específicos do provedor são mapeados para chats básicos, IDs de threads e alternativas de conversas pai
• Saída - envio de texto, mídia e enquetes para a plataforma
• Encadeamento - como as respostas são encadeadas
• Indicador de digitação do Heartbeat - sinais opcionais de digitação/ocupado para destinos de entrega do Heartbeat

​

Adaptador de mensagens

​

Entrada de mensagens recebidas (experimental)

​

Indicadores de digitação

​

Parâmetros de origem de mídia

​

Formatação de payloads nativos

​

Gramática de conversa da sessão

​

Compatibilidade com vinculação de conversas por conta

​

Aprovações e recursos do canal

​

Autorização de aprovação

• approvalCapability.authorizeActorAction e approvalCapability.getActionAvailabilityState são a interface canônica de autorização de aprovação.
• Use getActionAvailabilityState para verificar a disponibilidade da autorização de aprovação no mesmo chat. Mantenha os aprovadores configurados disponíveis para /approve mesmo quando a entrega nativa estiver desabilitada; use o estado nativo da superfície iniciadora para orientação sobre entrega/configuração.
• Se o canal expuser aprovações nativas de execução, use approvalCapability.getExecInitiatingSurfaceState para o estado da superfície iniciadora/cliente nativo quando ele for diferente da autorização de aprovação no mesmo chat. O núcleo usa esse gancho específico de execução para distinguir enabled de disabled, decidir se o canal iniciador comporta aprovações nativas de execução e incluir o canal na orientação de alternativa do cliente nativo. createApproverRestrictedNativeApprovalCapability(...) preenche isso para o caso comum.
• Se um canal puder inferir identidades estáveis, semelhantes às de proprietário, em mensagens diretas a partir da configuração existente, use createResolvedApproverActionAuthAdapter de openclaw/plugin-sdk/approval-runtime para restringir /approve no mesmo chat sem adicionar lógica específica de aprovação ao núcleo.
• Se a autorização personalizada de aprovação permitir intencionalmente apenas a alternativa no mesmo chat, retorne markImplicitSameChatApprovalAuthorization({ authorized: true }) de openclaw/plugin-sdk/approval-auth-runtime; caso contrário, o núcleo tratará o resultado como autorização explícita do aprovador.
• Se um callback nativo pertencente ao canal resolver aprovações diretamente, use isImplicitSameChatApprovalAuthorization(...) antes da resolução para que a alternativa implícita ainda passe pela autorização normal de atores do canal.

​

Ciclo de vida do payload e orientação de configuração

• Use outbound.shouldSuppressLocalPayloadPrompt ou outbound.beforeDeliverPayload para comportamentos do ciclo de vida do payload específicos do canal, como ocultar solicitações locais duplicadas de aprovação ou enviar indicadores de digitação antes da entrega.
• Use approvalCapability.describeExecApprovalSetup quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais opções de configuração são necessárias para habilitar aprovações nativas de execução. O gancho recebe { channel, channelLabel, accountId }; canais com contas nomeadas devem renderizar caminhos com escopo de conta, como channels.<channel>.accounts.<id>.execApprovals.*, em vez de padrões de nível superior.
• Use approvalCapability.describePluginApprovalSetup quando a orientação de falha de aprovação do Plugin puder ser exibida com segurança em falhas de aprovação do Plugin por ausência de rota ou tempo limite. createApproverRestrictedNativeApprovalCapability(...) não infere isso de describeExecApprovalSetup; passe explicitamente o mesmo auxiliar somente quando as aprovações do Plugin e de execução realmente usarem a mesma configuração nativa.

​

Entrega nativa de aprovações

• availability - se a conta está configurada e se uma solicitação deve ser processada
• presentation - mapear o modelo de visualização compartilhado de aprovação para payloads nativos pendentes/resolvidos/expirados ou ações finais
• transport - preparar destinos e enviar/atualizar/excluir mensagens nativas de aprovação
• interactions - hooks opcionais de vinculação/desvinculação/limpeza de ação para botões ou reações nativas, além de um hook cancelDelivered opcional. Implemente cancelDelivered quando deliverPending registrar um estado no processo ou persistente (como um armazenamento de destinos de reação), para que esse estado possa ser liberado se a interrupção de um manipulador cancelar a entrega antes da execução de bindPending, ou quando bindPending não retornar nenhum identificador
• observe - hooks opcionais de diagnóstico de entrega

• Use createNativeApprovalChannelRouteGates de openclaw/plugin-sdk/approval-native-runtime quando um canal oferecer suporte tanto à entrega nativa na origem da sessão quanto a destinos explícitos de encaminhamento de aprovação. O auxiliar centraliza a seleção da configuração de aprovação, o tratamento de mode, os filtros de agente/sessão, a vinculação de conta, a correspondência do destino da sessão e a correspondência da lista de destinos, enquanto os chamadores continuam responsáveis pelo ID do canal, pelo modo padrão de encaminhamento, pela busca da conta, pela verificação de transporte habilitado, pela normalização do destino e pela resolução do destino da origem do turno. Não o use para criar padrões de política de canal pertencentes ao núcleo; passe explicitamente o modo padrão documentado do canal.
• createChannelNativeOriginTargetResolver usa por padrão o comparador compartilhado de rotas de canal para destinos { to, accountId, threadId }. Passe targetsMatch somente quando um canal tiver regras de equivalência específicas do provedor, como a correspondência por prefixo de carimbo de data/hora do Slack. Passe normalizeTargetForMatch quando o canal precisar tornar canônicos os IDs do provedor antes da execução do comparador de rotas padrão ou de um retorno de chamada targetsMatch personalizado, preservando o destino original para entrega. Use normalizeTarget somente quando o próprio destino de entrega resolvido precisar ser tornado canônico.
• Se o canal precisar de objetos pertencentes ao runtime, como um cliente, token, aplicativo Bolt ou receptor de Webhook, registre-os por meio de openclaw/plugin-sdk/channel-runtime-context. O registro genérico de contexto do runtime permite que o núcleo inicialize manipuladores orientados por recursos a partir do estado de inicialização do canal sem adicionar código intermediário específico de aprovação.
• Use os auxiliares de nível inferior createChannelApprovalHandler ou createChannelNativeApprovalRuntime somente quando a interface orientada por recursos ainda não for expressiva o suficiente.
• Canais de aprovação nativa devem encaminhar tanto accountId quanto approvalKind por esses auxiliares. accountId mantém a política de aprovação para várias contas restrita à conta de bot correta, e approvalKind mantém o comportamento de aprovação de execução em comparação com Plugin disponível ao canal sem ramificações fixas no núcleo.
• O núcleo também é responsável pelos avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo “a aprovação foi para as DMs/outro canal” a partir de createChannelNativeApprovalRuntime; em vez disso, exponha o roteamento preciso da origem + DM do aprovador por meio dos auxiliares compartilhados de recursos de aprovação e deixe o núcleo agregar as entregas reais antes de publicar qualquer aviso de volta no chat de origem.
• Preserve de ponta a ponta o tipo do ID de aprovação entregue. Clientes nativos não devem tentar adivinhar nem reescrever o roteamento de aprovação de execução em comparação com Plugin com base no estado local do canal.
• Passe esse approvalKind explícito para resolveApprovalOverGateway. Isso usa o serviço canônico approval.resolve e retorna o vencedor registrado quando outra superfície responde primeiro. A entrada explícita resolveMethod mais antiga permanece para controles baseados em comandos; novas ações nativas não devem usá-la nem inferir o tipo a partir de um ID.
• Diferentes tipos de aprovação podem expor intencionalmente diferentes superfícies nativas. Exemplos incluídos atualmente: Matrix mantém o mesmo roteamento nativo de DM/canal e a mesma experiência de reações para aprovações de execução e de Plugin, enquanto ainda permite que a autenticação varie conforme o tipo de aprovação; Slack mantém o roteamento de aprovação nativa disponível tanto para IDs de execução quanto de Plugin.
• createApproverRestrictedNativeApprovalAdapter ainda existe como um wrapper de compatibilidade, mas o código novo deve preferir o construtor de recursos e expor approvalCapability no Plugin.

​

Subcaminhos mais específicos do runtime de aprovação

• openclaw/plugin-sdk/approval-auth-runtime
• openclaw/plugin-sdk/approval-client-runtime
• openclaw/plugin-sdk/approval-delivery-runtime
• openclaw/plugin-sdk/approval-gateway-runtime
• openclaw/plugin-sdk/approval-reference-runtime
• openclaw/plugin-sdk/approval-handler-adapter-runtime
• openclaw/plugin-sdk/approval-handler-runtime
• openclaw/plugin-sdk/approval-native-runtime
• openclaw/plugin-sdk/approval-reply-runtime
• openclaw/plugin-sdk/channel-runtime-context

​

Subcaminhos de configuração

• openclaw/plugin-sdk/setup-runtime abrange os auxiliares de configuração seguros para o runtime: createSetupTranslator, adaptadores de patch de configuração seguros para importação (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), saída de notas de busca, promptResolvedAllowFrom, splitSetupEntries e os construtores delegados de proxy de configuração.
• openclaw/plugin-sdk/channel-setup abrange os construtores de configuração para instalação opcional e alguns componentes básicos seguros para configuração: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled e splitSetupEntries.
• Use a interface mais ampla openclaw/plugin-sdk/setup somente quando também precisar dos auxiliares compartilhados mais pesados de configuração, como moveSingleAccountChannelSectionToDefaultAccount(...).

​

Outros subcaminhos específicos de canal

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution e openclaw/plugin-sdk/account-helpers para configuração de várias contas e fallback para a conta padrão
• openclaw/plugin-sdk/inbound-envelope e openclaw/plugin-sdk/channel-inbound para rota/envelope de entrada e integração de registro e despacho
• openclaw/plugin-sdk/channel-targets para auxiliares de análise de destino
• openclaw/plugin-sdk/outbound-media para carregamento de mídia e openclaw/plugin-sdk/channel-outbound para delegados de identidade/envio de saída e planejamento de payload
• buildThreadAwareOutboundSessionRoute(...) de openclaw/plugin-sdk/channel-core quando uma rota de saída deve preservar um replyToId/threadId explícito ou recuperar a sessão :thread: atual depois que a chave de sessão base ainda corresponder. Plugins de provedor podem substituir a precedência, o comportamento do sufixo e a normalização do ID da thread quando sua plataforma tiver semântica nativa de entrega em threads.
• openclaw/plugin-sdk/thread-bindings-runtime para o ciclo de vida da vinculação de threads e o registro de adaptadores
• openclaw/plugin-sdk/agent-media-payload somente quando o layout legado dos campos de payload de agente/mídia ainda for necessário
• openclaw/plugin-sdk/telegram-command-config (obsoleto: nenhum Plugin incluído o utiliza em produção) para normalização de comandos personalizados do Telegram, validação de duplicatas/conflitos e um contrato de configuração de comandos estável em caso de fallback; para código novo de Plugin, prefira o tratamento local da configuração de comandos no Plugin

​

Política de menções de entrada

• coleta de evidências pertencente ao Plugin
• avaliação de política compartilhada

• detecção de resposta ao bot
• detecção de citação do bot
• verificações de participação na thread
• exclusões de mensagens de serviço/sistema
• caches nativos da plataforma necessários para comprovar a participação do bot

• requireMention
• resultado de menção explícita
• lista de permissões de menções implícitas
• desvio para comandos
• decisão final de ignorar

1. Calcule os fatos locais sobre menções.
2. Passe esses fatos para resolveInboundMentionDecision({ facts, policy }).
3. Use decision.effectiveWasMentioned, decision.shouldBypassMention e decision.shouldSkip no bloqueio de entrada.

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

​

Passo a passo

{
  "name": "@myorg/openclaw-acme-chat",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "acme-chat",
      "label": "Acme Chat",
      "blurb": "Conecte o OpenClaw ao Acme Chat."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Plugin de canal do Acme Chat",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "channelConfigs": {
    "acme-chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "token": { "type": "string" },
          "allowFrom": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "uiHints": {
        "token": {
          "label": "Token do bot",
          "sensitive": true
        }
      }
    }
  }
}

import {
  createChatChannelPlugin,
  createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // cliente da API da sua plataforma

type ResolvedAccount = {
  accountId: string | null;
  token: string;
  allowFrom: string[];
  dmPolicy: string | undefined;
};

function resolveAccount(
  cfg: OpenClawConfig,
  accountId?: string | null,
): ResolvedAccount {
  const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
  const token = section?.token;
  if (!token) throw new Error("acme-chat: o token é obrigatório");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // A resolução/inspeção da conta pertence a `config`, não a `setup`.
    // `setup` abrange gravações de integração (applyAccountConfig, validateInput).
    config: {
      listAccountIds: () => ["default"],
      resolveAccount,
      inspectAccount(cfg, accountId) {
        const section =
          (cfg.channels as Record<string, any>)?.["acme-chat"];
        return {
          enabled: Boolean(section?.token),
          configured: Boolean(section?.token),
          tokenStatus: section?.token ? "available" : "missing",
        };
      },
    },
    setup: {
      applyAccountConfig: ({ cfg, input }) => ({
        ...cfg,
        channels: {
          ...cfg.channels,
          "acme-chat": { ...(cfg.channels as any)?.["acme-chat"], ...input },
        },
      }),
    },
  }),

  // Segurança de MD: quem pode enviar mensagens ao bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Pareamento: fluxo de aprovação para novos contatos de MD
  pairing: {
    text: {
      idLabel: "Nome de usuário do Acme Chat",
      message: "Envie este código para verificar sua identidade:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Código de pareamento: ${code}`);
      },
    },
  },

  // Encadeamento: como as respostas são entregues
  threading: { topLevelReplyToMode: "reply" },

  // Saída: envia mensagens para a plataforma
  outbound: {
    attachedResults: {
      channel: "acme-chat",
      sendText: async (params) => {
        const result = await acmeChatApi.sendMessage(
          params.to,
          params.text,
        );
        return { messageId: result.id };
      },
    },
    base: {
      sendMedia: async (params) => {
        await acmeChatApi.sendFile(params.to, params.filePath);
      },
    },
  },
});

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineChannelPluginEntry({
  id: "acme-chat",
  name: "Acme Chat",
  description: "Plugin de canal do Acme Chat",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Gerenciamento do Acme Chat");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Gerenciamento do Acme Chat",
            hasSubcommands: false,
          },
        ],
      },
    );
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(acmeChatPlugin);

registerFull(api) {
  api.registerHttpRoute({
    path: "/acme-chat/webhook",
    auth: "plugin", // autenticação gerenciada pelo plugin (verifique você mesmo as assinaturas)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Seu manipulador de entrada despacha a mensagem para o OpenClaw.
      // A conexão exata depende do SDK da sua plataforma —
      // consulte um exemplo real no pacote do plugin agrupado do Microsoft Teams ou Google Chat.
      await handleAcmeChatInbound(api, event);

      res.statusCode = 200;
      res.end("ok");
      return true;
    },
  });
}

import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";

describe("acme-chat plugin", () => {
  it("resolves account from config", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.config.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("inspects account without materializing secrets", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("reports missing config", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

pnpm test <bundled-plugin-root>/acme-chat/

​

Estrutura de arquivos

<bundled-plugin-root>/acme-chat/
├── package.json              # Metadados de openclaw.channel
├── openclaw.plugin.json      # Manifesto com esquema de configuração
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Exportações públicas (opcional)
├── runtime-api.ts            # Exportações internas de runtime (opcional)
└── src/
    ├── channel.ts            # ChannelPlugin por meio de createChatChannelPlugin
    ├── channel.test.ts       # Testes
    ├── client.ts             # Cliente da API da plataforma
    └── runtime.ts            # Armazenamento de runtime (se necessário)

​

Tópicos avançados

​

Próximas etapas

• Plugins de provedor - se o seu plugin também fornecer modelos
• Visão geral do SDK - referência completa de importação de subcaminhos
• Testes do SDK - utilitários de teste e testes de contrato
• Manifesto do Plugin - esquema completo do manifesto

​

Relacionados

• Configuração do SDK de Plugin
• Criação de plugins
• Plugins do harness de agente