OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Desenvolvimento de plugins

Plugins ampliam o OpenClaw sem alterar o núcleo. Um plugin pode adicionar um canal de mensagens, provedor de modelos, backend de CLI local, ferramenta de agente, hook, provedor de mídia ou outra funcionalidade pertencente ao plugin.

Não é necessário adicionar um plugin externo ao repositório do OpenClaw. Publique o pacote no ClawHub, e os usuários poderão instalá-lo com:

bash
openclaw plugins install clawhub:<package-name>

Especificações de pacote sem prefixo ainda são instaladas do npm durante a transição de lançamento. Use o prefixo clawhub: quando quiser a resolução pelo ClawHub.

Requisitos

  • Node 22.22.3+, Node 24.15+ ou Node 25.9+, e npm ou pnpm.
  • Módulos ESM TypeScript.
  • Para trabalhar em um plugin incluído no repositório, clone o repositório e execute pnpm install. O desenvolvimento de plugins no checkout do código-fonte usa somente pnpm porque o OpenClaw descobre plugins incluídos nos pacotes do workspace extensions/*.

Escolha o formato do plugin

Plugin de canal

Conecte o OpenClaw a uma plataforma de mensagens.
Plugin de provedor

Adicione um provedor de modelos, mídia, pesquisa, busca, fala ou comunicação em tempo real.
Plugin de backend de CLI

Execute uma CLI de IA local por meio do fallback de modelo do OpenClaw.
Plugin de ferramenta

Registre ferramentas de agente.

Início rápido

Crie um plugin de ferramenta mínimo registrando uma ferramenta de agente obrigatória. Este é o formato útil mais simples de plugin e abrange o pacote, o manifesto, o ponto de entrada e a validação local.

  • Criar os metadados do pacote

    package.json
    {"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"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    Plugins externos publicados devem direcionar as entradas de runtime para arquivos JavaScript compilados. Consulte Pontos de entrada do SDK para ver o contrato completo dos pontos de entrada.

    Todo plugin precisa de um manifesto, mesmo sem configuração. As ferramentas de runtime devem constar em contracts.tools para que o OpenClaw possa descobrir a propriedade sem carregar antecipadamente o runtime de todos os plugins. Defina activation.onStartup intencionalmente; este exemplo é carregado na inicialização do Gateway.

    As superfícies de plugin consideradas confiáveis pelo host também são controladas pelo manifesto e exigem uma declaração explícita para plugins instalados: api.registerAgentToolResultMiddleware(...) requer que cada runtime de destino seja listado em contracts.agentToolResultMiddleware, e api.registerTrustedToolPolicy(...) requer cada ID de política em contracts.trustedToolPolicies. Essas declarações mantêm alinhadas a inspeção no momento da instalação e o registro no runtime.

    Para todos os campos do manifesto, consulte Manifesto de plugin.

  • Registrar a ferramenta

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    Use definePluginEntry para plugins que não sejam de canal. Plugins de canal usam defineChannelPluginEntry de openclaw/plugin-sdk/core.

  • Testar o runtime

    Para um plugin instalado ou externo, inspecione o runtime carregado:

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Se o plugin registrar um comando de CLI, execute também esse comando e confirme a saída, por exemplo, openclaw demo-plugin ping.

    Para um plugin incluído neste repositório, o OpenClaw descobre os pacotes de plugin do checkout do código-fonte no workspace extensions/*. Execute o teste direcionado mais próximo:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Testar a instalação do pacote

    Antes de publicar um plugin pronto para empacotamento, teste o mesmo formato de instalação que os usuários receberão. Primeiro, adicione uma etapa de build, direcione entradas de runtime como openclaw.extensions para JavaScript compilado, como ./dist/index.js, e garanta que npm pack inclua essa saída dist/. Entradas de código-fonte TypeScript são apenas para checkouts do código-fonte e caminhos de desenvolvimento local.

    Em seguida, empacote o plugin e instale o tarball com npm-pack::

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: usa o projeto npm gerenciado por plugin do OpenClaw, portanto detecta erros de dependência de runtime que os testes no checkout do código-fonte podem ocultar. Ele comprova o formato do pacote e das dependências, não a confiança oficial vinculada ao catálogo. As importações de runtime devem estar em dependencies ou optionalDependencies; dependências deixadas apenas em devDependencies não serão instaladas para o projeto de runtime gerenciado.

    Não use uma instalação por arquivo bruto/caminho como validação final para comportamentos de plugins oficiais ou privilegiados. Códigos-fonte brutos são úteis para depuração local, mas não comprovam o mesmo caminho de dependências que instalações pelo npm ou ClawHub. Se o plugin depender do status confiável de plugin oficial, adicione uma segunda validação por meio de uma instalação oficial respaldada por catálogo ou de um caminho de pacote publicado que registre a confiança oficial. Consulte Resolução de dependências de plugins para obter detalhes sobre a raiz de instalação e a propriedade das dependências.

  • Publicar

    Valide o pacote antes de publicar:

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

    Os trechos canônicos de pacotes do ClawHub ficam em docs/snippets/plugin-publish/.

  • Instalar

    Instale o pacote publicado pelo ClawHub:

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • Registro de ferramentas

    As ferramentas podem ser obrigatórias ou opcionais. As ferramentas obrigatórias ficam sempre disponíveis quando o plugin está habilitado. As ferramentas opcionais exigem consentimento explícito do usuário antes que o OpenClaw carregue o runtime do plugin proprietário.

    As fábricas de ferramentas recebem um contexto de runtime confiável, incluindo deliveryContext, nativeChannelId para a conversa ativa da plataforma, quando disponível, e requesterSenderId.

    typescript
    register(api) {  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 },  );}

    Toda ferramenta registrada com api.registerTool(...) também deve ser declarada no manifesto do plugin:

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    Os usuários dão consentimento com tools.allow:

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    As ferramentas opcionais controlam se uma ferramenta é exposta ao modelo. Use solicitações de permissão de plugins quando uma ferramenta ou hook precisar solicitar aprovação depois que o modelo a selecionar e antes que a ação seja executada.

    Use ferramentas opcionais para efeitos colaterais, binários incomuns ou funcionalidades que não devem ser expostas por padrão. Os nomes das ferramentas não podem entrar em conflito com nomes de ferramentas do núcleo; os conflitos são ignorados e relatados nos diagnósticos de plugins. Registros malformados são ignorados e relatados da mesma maneira: um name não vazio ausente, um execute que não seja uma função ou um descritor de ferramenta sem um objeto parameters.

    As fábricas de ferramentas recebem um objeto de contexto fornecido pelo runtime. Use ctx.activeModel quando uma ferramenta precisar registrar, exibir ou se adaptar ao modelo ativo na execução atual; ele pode incluir provider, modelId e modelRef. Trate-o como metadados informativos de runtime, não como um limite de segurança contra o operador local, o código de plugin instalado ou um runtime modificado do OpenClaw. Ferramentas locais sensíveis ainda devem exigir consentimento explícito do plugin ou do operador e falhar de modo seguro quando os metadados do modelo ativo estiverem ausentes ou forem inadequados.

    O manifesto declara a propriedade e a descoberta; a execução ainda chama a implementação ativa da ferramenta registrada. Mantenha toolMetadata.<tool>.optional: true alinhado com api.registerTool(..., { optional: true }) para que o OpenClaw possa evitar carregar o runtime desse plugin até que a ferramenta seja explicitamente adicionada à lista de permissões.

    Convenções de importação

    Importe de subcaminhos específicos do SDK:

    typescript

    Não importe do barrel raiz obsoleto:

    typescript

    Dentro do pacote do plugin, use arquivos barrel locais, como api.ts e runtime-api.ts, para importações internas. Não importe o próprio plugin por meio de um caminho do SDK. Helpers específicos de provedores devem permanecer no pacote do provedor, a menos que a interface seja realmente genérica.

    Métodos RPC personalizados do Gateway são um ponto de entrada avançado. Mantenha-os em um prefixo específico do plugin; namespaces administrativos do núcleo, como config.*, exec.approvals.*, operator.admin.*, wizard.* e update.*, permanecem reservados e são resolvidos como operator.admin. A ponte openclaw/plugin-sdk/gateway-method-runtime é reservada para rotas HTTP de plugins que declaram contracts.gatewayMethodDispatch: ["authenticated-request"].

    Para ver o mapa completo de importações, consulte Visão geral do SDK de plugins.

    Lista de verificação antes do envio

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json contém os metadados openclaw corretos OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s O manifesto openclaw.plugin.json está presente e é válido OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s O ponto de entrada usa defineChannelPluginEntry ou definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Todas as importações usam caminhos plugin-sdk/<subpath> específicos OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page