​

Building Plugins

​

Pré-requisitos

• Node >= 22 e um gerenciador de pacotes (npm ou pnpm)
• Familiaridade com TypeScript (ESM)
• Para plugins no repositório: repositório clonado e pnpm install executado

​

Que tipo de plugin?

​

Início rápido: plugin de ferramenta

{
  "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"
    }
  }
}

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

​

Capacidades de plugin

• before_tool_call: { block: true } é terminal e interrompe handlers de prioridade mais baixa.
• before_tool_call: { block: false } é tratado como nenhuma decisão.
• before_tool_call: { requireApproval: true } pausa a execução do agente e solicita aprovação do usuário por meio da sobreposição de aprovação de execução, botões do Telegram, interações do Discord ou o comando /approve em qualquer canal.
• before_install: { block: true } é terminal e interrompe handlers de prioridade mais baixa.
• before_install: { block: false } é tratado como nenhuma decisão.
• message_sending: { cancel: true } é terminal e interrompe handlers de prioridade mais baixa.
• message_sending: { cancel: false } é tratado como nenhuma decisão.

​

Registrando ferramentas de agente

register(api) {
  // Ferramenta obrigatória — sempre disponível
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Ferramenta opcional — o usuário deve adicioná-la à allowlist
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

{
  tools: { allow: ["workflow_tool"] },
}

• Os nomes das ferramentas não devem conflitar com ferramentas centrais (conflitos são ignorados)
• Use optional: true para ferramentas com efeitos colaterais ou requisitos binários extras
• Os usuários podem habilitar todas as ferramentas de um plugin adicionando o id do plugin a tools.allow

​

Convenções de importação

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Errado: raiz monolítica (obsoleta, será removida)
import { ... } from "openclaw/plugin-sdk";

• Anthropic: wrappers de stream do Claude e helpers de service_tier / beta
• OpenAI: builders de provedor, helpers de modelo padrão, provedores em tempo real
• OpenRouter: builder de provedor mais helpers de onboarding/configuração

​

Checklist antes do envio

​

Testes de versão beta

1. Fique de olho nas tags de release do GitHub em openclaw/openclaw e inscreva-se via Watch > Releases. As tags beta têm aparência como v2026.3.N-beta.1. Você também pode ativar notificações para a conta oficial do OpenClaw no X @openclaw para anúncios de release.
2. Teste seu plugin com a tag beta assim que ela aparecer. A janela antes da versão estável normalmente é de apenas algumas horas.
3. Publique na thread do seu plugin no canal plugin-forum do Discord após o teste com all good ou informando o que quebrou. Se você ainda não tiver uma thread, crie uma.
4. Se algo quebrar, abra ou atualize uma issue intitulada Beta blocker: <plugin-name> - <summary> e aplique o rótulo beta-blocker. Coloque o link da issue na sua thread.
5. Abra um PR para main com o título fix(<plugin-id>): beta blocker - <summary> e vincule a issue tanto no PR quanto na sua thread no Discord. Colaboradores não podem rotular PRs, então o título é o sinal do lado do PR para mantenedores e automação. Bloqueadores com PR são mesclados; bloqueadores sem PR podem ser enviados mesmo assim. Mantenedores acompanham essas threads durante os testes beta.
6. Silêncio significa verde. Se você perder a janela, sua correção provavelmente entrará no próximo ciclo.

​

Próximos passos

​

Relacionado

• Plugin Architecture — análise detalhada da arquitetura interna
• SDK Overview — referência do Plugin SDK
• Manifest — formato do manifesto de plugin
• Channel Plugins — criação de plugins de canal
• Provider Plugins — criação de plugins de provedor