OpenClawDocs

Search...K

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:

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

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.

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

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.

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

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

{  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:

Não importe do barrel raiz obsoleto:

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:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Os testes passam (pnpm test <bundled-plugin-root>/my-plugin/) OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s pnpm check passa (plugins no repositório) OPENCLAW_DOCS_MARKER:calloutClose:

Teste com versões beta

1. Acompanhe as versões de openclaw/openclaw (Watch > Releases). As tags beta têm a seguinte aparência: v2026.3.N-beta.1. Também é possível seguir @openclaw no X para receber anúncios de versões.
2. Teste seu plugin com a tag beta assim que ela aparecer. O intervalo antes da versão estável normalmente é de apenas algumas horas.
3. Após os testes, publique na thread do seu plugin no canal plugin-forum do Discord (discord.gg/clawd), informando all good ou o que deixou de funcionar. Crie uma thread caso ainda não tenha uma.
4. Se algo deixar de funcionar, abra ou atualize uma issue com o título Beta blocker: <plugin-name> - <summary> e aplique o rótulo beta-blocker. Inclua o link da issue na sua thread.
5. Abra um PR para main com o título fix(<plugin-id>): beta blocker - <summary> e inclua o link da issue tanto no PR quanto na sua thread do Discord. Colaboradores não podem aplicar rótulos a PRs, portanto o título é o sinal no PR para os mantenedores e a automação. Bloqueios com um PR são mesclados; bloqueios sem um PR podem acabar sendo lançados mesmo assim.
6. O silêncio indica que está tudo certo. Perder o prazo normalmente significa que sua correção será incluída no próximo ciclo.

Próximas etapas

Relacionados

• Hooks de plugin
• Arquitetura de plugins

Install OpenClawSet up TelegramFix GatewayBuild a plugin

Ask Molty

Ask Molty

Molty

Responses are generated using AI and may contain mistakes.