Migração do SDK de Plugin

​

O que mudou

• openclaw/plugin-sdk/compat - reexportava dezenas de auxiliares para manter plugins antigos baseados em hooks funcionando enquanto a nova arquitetura era desenvolvida.
• openclaw/plugin-sdk/infra-runtime - um barrel amplo que combinava eventos do sistema, estado de heartbeat, filas de entrega, auxiliares de fetch/proxy, auxiliares de arquivos, tipos de aprovação e utilitários sem relação entre si.
• openclaw/plugin-sdk/config-runtime - um barrel amplo de configuração que ainda mantinha auxiliares diretos obsoletos de carregamento/gravação durante o período de migração.
• openclaw/extension-api - uma ponte que dava aos plugins acesso direto a auxiliares do host, como o executor de agente incorporado.
• api.registerEmbeddedExtensionFactory(...) - um hook removido, exclusivo do executor incorporado, que observava eventos desse executor, como tool_result. Em vez disso, use middleware de resultados de ferramentas do agente (consulte Migrar extensões de resultados de ferramentas incorporadas para middleware).

​

Por quê

• Inicialização lenta - importar um auxiliar carregava dezenas de módulos não relacionados.
• Dependências circulares - reexportações amplas facilitavam a criação de ciclos de importação.
• Superfície de API pouco clara - não havia como distinguir exportações estáveis das internas.

• A Anthropic mantém auxiliares de stream específicos do Claude em sua própria interface api.ts / contract-api.ts.
• A OpenAI mantém construtores de provedores, auxiliares de modelo padrão e construtores de provedores em tempo real em seu próprio api.ts.
• A OpenRouter mantém o construtor de provedor e os auxiliares de integração/configuração em seu próprio api.ts.

​

Política de compatibilidade

1. Adicionar o novo contrato.
2. Manter o comportamento antigo conectado por meio de um adaptador de compatibilidade.
3. Emitir um diagnóstico ou aviso que indique o caminho antigo e seu substituto.
4. Abranger ambos os caminhos em testes.
5. Documentar a descontinuação e o caminho de migração.
6. Remover somente após o período de migração anunciado, geralmente em uma versão principal.

​

Como migrar

await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});

// Ferramentas dinâmicas dos ambientes de execução OpenClaw e Codex
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}

// Antes
const program = applyWindowsSpawnProgramPolicy({ candidate });

// Depois
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Defina isto somente para chamadores de compatibilidade confiáveis que aceitem
  // intencionalmente o fallback intermediado pelo shell.
  allowShellFallback: true,
});

grep -r "plugin-sdk/compat" my-plugin/
grep -r "plugin-sdk/infra-runtime" my-plugin/
grep -r "plugin-sdk/config-runtime" my-plugin/
grep -r "openclaw/extension-api" my-plugin/

// Antes (camada de compatibilidade retroativa obsoleta)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// Depois (importações modernas e específicas)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// Antes (ponte extension-api obsoleta)
import { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// Depois (runtime injetado)
const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm build
pnpm test my-plugin/

​

Referência de caminhos de importação

​

Descontinuações ativas

// Antes
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// Depois
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Antes
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Depois
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});

// Antes
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// Depois
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});

{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}

// Antes
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// Depois
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Antes
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// Depois
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

​

Migração do Talk e de voz em tempo real

// API de sessão do Talk pertencente ao Gateway.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// API de sessão de provedor pertencente ao cliente.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

​

Cronograma de remoção

​

Suprimir temporariamente os avisos

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

​

Relacionados

• Primeiros passos - crie seu primeiro plugin
• Visão geral do SDK - referência completa de importação de subcaminhos
• Plugins de canal - criação de plugins de canal
• Plugins de provedor - criação de plugins de provedor
• Detalhes internos dos plugins - análise aprofundada da arquitetura
• Manifesto do plugin - referência do esquema do manifesto