Criando plugins

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

Você não precisa adicionar um plugin externo ao repositório do OpenClaw. Publique o pacote no ClawHub e os usuários o instalam com:

openclaw plugins install clawhub:<package-name>

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

Requisitos

• Use Node 22.19+, Node 23.11+ ou Node 24+ e um gerenciador de pacotes como npm ou pnpm.
• Tenha familiaridade com módulos ESM do TypeScript.
• Para trabalho em plugin empacotado dentro do repositório, clone o repositório e execute pnpm install. O desenvolvimento de plugins em checkout de código-fonte usa apenas pnpm porque o OpenClaw carrega plugins empacotados a partir dos pacotes de workspace extensions/*.

Escolha o formato do plugin

Início rápido

Crie um plugin de ferramenta mínimo registrando uma ferramenta de agente obrigatória. Este é o formato útil mais curto de plugin e mostra o pacote, o manifesto, o ponto de entrada e a prova local.

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

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

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

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

pnpm test -- extensions/my-plugin/pnpm check

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

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

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

Registrando ferramentas

Ferramentas podem ser obrigatórias ou opcionais. Ferramentas obrigatórias estão sempre disponíveis quando o Plugin está habilitado. Ferramentas opcionais exigem adesão do usuário.

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:

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

Usuários aderem com tools.allow:

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

Ferramentas opcionais controlam se uma ferramenta é exposta ao modelo. Use solicitações de permissão de Plugin quando uma ferramenta ou hook deve pedir aprovação depois que o modelo a seleciona e antes que a ação seja executada.

Use ferramentas opcionais para efeitos colaterais, binários incomuns ou capacidades que não devem ser expostas por padrão. Nomes de ferramentas não podem conflitar com ferramentas principais; conflitos são ignorados e relatados nos diagnósticos do Plugin. Registros malformados, incluindo descritores de ferramenta sem parameters, são ignorados e relatados da mesma forma. Ferramentas registradas são funções tipadas que o modelo pode chamar depois que as verificações de política e lista de permissões são aprovadas.

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 do turno atual. O objeto pode incluir provider, modelId e modelRef. Trate-o como metadados informativos de runtime, não como uma fronteira de segurança contra o operador local, código de Plugin instalado ou um runtime do OpenClaw modificado. Ferramentas locais sensíveis ainda devem exigir uma adesão explícita do Plugin ou operador e falhar de modo fechado quando os metadados de modelo ativo estiverem ausentes ou forem inadequados.

O manifesto declara propriedade e descoberta; a execução ainda chama a implementação registrada ativa da ferramenta. 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 incluída na lista de permissões.

Convenções de importação

Importe de subcaminhos focados do SDK:

Não importe do barrel raiz obsoleto:

Dentro do seu pacote de Plugin, use arquivos barrel locais, como api.ts e runtime-api.ts, para importações internas. Não importe seu próprio Plugin por meio de um caminho do SDK. Helpers específicos de provedor 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 principais, como config.*, exec.approvals.*, operator.admin.*, wizard.* e update.*, permanecem reservados e resolvem para operator.admin. A ponte openclaw/plugin-sdk/gateway-method-runtime é reservada para rotas HTTP de Plugin que declaram contracts.gatewayMethodDispatch: ["authenticated-request"].

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

Lista de verificação de pré-envio

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json tem 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 focados plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: