Auxiliares de runtime de Plugin

Identidade, diretórios e gerenciamento de sessão do agente.

// Resolve the agent's working directoryconst agentDir = api.runtime.agent.resolveAgentDir(cfg); // Resolve agent workspaceconst workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); // Get agent identityconst identity = api.runtime.agent.resolveAgentIdentity(cfg); // Get default thinking levelconst thinking = api.runtime.agent.resolveThinkingDefault({  cfg,  provider,  model,}); // Validate a user-provided thinking level against the active provider profileconst policy = api.runtime.agent.resolveThinkingPolicy({ provider, model });const level = api.runtime.agent.normalizeThinkingLevel("extra high");if (level && policy.levels.some((entry) => entry.id === level)) {  // pass level to an embedded run} // Get agent timeoutconst timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Ensure workspace existsawait api.runtime.agent.ensureAgentWorkspace(cfg); // Run an embedded agent turnconst result = await api.runtime.agent.runEmbeddedAgent({  sessionId: "my-plugin:task-1",  runId: crypto.randomUUID(),  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),  prompt: "Summarize the latest changes",  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),});

runEmbeddedAgent(...) é o auxiliar neutro para iniciar um turno normal de agente do OpenClaw a partir do código de plugin. Ele usa a mesma resolução de provedor/modelo e seleção de harness de agente que as respostas acionadas por canal.

runEmbeddedPiAgent(...) permanece como um alias de compatibilidade obsoleto para plugins existentes. Código novo deve usar runEmbeddedAgent(...).

resolveThinkingPolicy(...) retorna os níveis de raciocínio compatíveis do provedor/modelo e o padrão opcional. Plugins de provedor são responsáveis pelo perfil específico do modelo por meio de seus hooks de raciocínio, portanto plugins de ferramenta devem chamar este auxiliar de runtime em vez de importar ou duplicar listas de provedores.

normalizeThinkingLevel(...) converte texto de usuário, como on, x-high ou extra high, para o nível armazenado canônico antes de verificá-lo contra a política resolvida.

Auxiliares do armazenamento de sessão ficam em api.runtime.agent.session:

const entry = api.runtime.agent.session.getSessionEntry({ agentId, sessionKey });for (const { sessionKey, entry } of api.runtime.agent.session.listSessionEntries({ agentId })) {  // Iterate session rows without depending on the legacy sessions.json shape.}await api.runtime.agent.session.patchSessionEntry({  agentId,  sessionKey,  update: (entry) => ({ thinkingLevel: "high" }),}); const storePath = api.runtime.agent.session.resolveStorePath(cfg.session?.store, { agentId });await api.runtime.agent.session.runWithWorkAdmission(  { storePath, sessionKey },  async (signal) => {    // Create or update the session, then pass signal to the admitted agent run.  },);

Prefira getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) ou upsertSessionEntry(...) para fluxos de trabalho de sessão. Esses auxiliares endereçam sessões por identidade de agente/sessão para que plugins não dependam da forma legada de armazenamento sessions.json. Use preserveActivity: true para patches somente de metadados que não devem atualizar a atividade da sessão, e replaceEntry: true somente quando o callback retornar uma entrada completa e campos excluídos precisarem permanecer excluídos.

Use runWithWorkAdmission(...) quando um plugin inicia trabalho em uma sessão persistida. O callback rejeita sessões arquivadas ou substituídas concorrentemente, mantém mutações de arquivamento/redefinição/exclusão coordenadas até a conclusão e recebe um AbortSignal que deve ser encaminhado para a execução do agente.

Para leituras e gravações de transcrição, importe openclaw/plugin-sdk/session-transcript-runtime e use resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) ou withSessionTranscriptWriteLock(...) com { agentId, sessionKey, sessionId }. Essas APIs permitem que plugins identifiquem uma transcrição, leiam seus eventos, anexem mensagens, publiquem atualizações e executem operações relacionadas sob o mesmo bloqueio de gravação de transcrição. Passar sessionFile, usar resolveSessionTranscriptLegacyFileTarget(...) ou importar appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) de baixo nível de openclaw/plugin-sdk/agent-harness-runtime está obsoleto; esses caminhos existem apenas para código legado que já recebe um artefato de transcrição ativo.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) e resolveAndPersistSessionFile(...) são auxiliares de compatibilidade obsoletos para plugins que ainda dependem intencionalmente da forma legada de armazenamento completo ou arquivo de transcrição. Código novo de plugin não deve usar esses auxiliares, e chamadores existentes devem migrar para auxiliares de entrada e auxiliares de identidade de transcrição.

Constantes padrão de modelo e provedor:

const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"

Execute uma conclusão de texto pertencente ao host sem importar componentes internos de provedor nem duplicar a preparação de modelo/autenticação/URL base do OpenClaw.

const result = await api.runtime.llm.complete({  messages: [{ role: "user", content: "Summarize this transcript." }],  purpose: "my-plugin.summary",  maxTokens: 512,  temperature: 0.2,});

O auxiliar usa o mesmo caminho de preparação de conclusão simples do runtime integrado do OpenClaw e o snapshot de configuração de runtime pertencente ao host. Mecanismos de contexto recebem uma capacidade llm.complete vinculada à sessão, então chamadas de modelo usam o agente da sessão ativa e não recorrem silenciosamente ao agente padrão. O resultado inclui atribuição de provedor/modelo/agente mais uso normalizado de tokens, cache e custo estimado quando disponível.

Inicie e gerencie execuções de subagentes em segundo plano.

// Start a subagent runconst { runId } = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "Expand this query into focused follow-up searches.",  provider: "openai", // optional override  model: "gpt-4.1-mini", // optional override  deliver: false,}); // Wait for completionconst result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); // Read session messagesconst { messages } = await api.runtime.subagent.getSessionMessages({  sessionKey: "agent:main:subagent:search-helper",  limit: 10,}); // Delete a sessionawait api.runtime.subagent.deleteSession({  sessionKey: "agent:main:subagent:search-helper",});

deleteSession(...) pode excluir sessões criadas pelo mesmo plugin por meio de api.runtime.subagent.run(...). Excluir sessões arbitrárias de usuário ou operador ainda exige uma solicitação ao Gateway com escopo de administrador.

Liste nós conectados e invoque um comando hospedado em nó a partir de código de plugin carregado pelo Gateway ou de comandos de CLI do plugin. Use isto quando um plugin for proprietário de trabalho local em um dispositivo pareado, por exemplo uma ponte de navegador ou áudio em outro Mac.

const { nodes } = await api.runtime.nodes.list({ connected: true }); const result = await api.runtime.nodes.invoke({  nodeId: "mac-studio",  command: "my-plugin.command",  params: { action: "start" },  timeoutMs: 30000,});

Dentro do Gateway, este runtime é no processo. Em comandos de CLI do plugin, ele chama o Gateway configurado por RPC, então comandos como openclaw googlemeet recover-tab podem inspecionar nós pareados a partir do terminal. Comandos de Node ainda passam pelo pareamento normal de nós do Gateway, listas de permissões de comandos, políticas de invocação de nó do plugin e tratamento de comandos locais ao nó.

Plugins que expõem comandos perigosos hospedados em nó devem registrar uma política de invocação de nó com api.registerNodeInvokePolicy(...). A política é executada no Gateway após verificações da lista de permissões de comandos e antes de o comando ser encaminhado ao nó, então chamadas diretas de node.invoke e ferramentas de plugin de nível mais alto compartilham o mesmo caminho de imposição.

Vincule um runtime de Task Flow a uma chave de sessão existente do OpenClaw ou a um contexto de ferramenta confiável e, em seguida, crie e gerencie Task Flows sem passar um proprietário em cada chamada.

O Task Flow rastreia estado durável de workflow em várias etapas. Ele não é um agendador: use Cron ou api.session.workflow.scheduleSessionTurn(...) para futuros despertares e, em seguida, use managedFlows a partir do turno agendado quando esse trabalho precisar de estado de fluxo, tarefas filhas, esperas ou cancelamento.

const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx); const created = taskFlow.createManaged({  controllerId: "my-plugin/review-batch",  goal: "Review new pull requests",}); const child = taskFlow.runTask({  flowId: created.flowId,  runtime: "acp",  childSessionKey: "agent:main:subagent:reviewer",  task: "Review PR #123",  status: "running",  startedAt: Date.now(),}); const waiting = taskFlow.setWaiting({  flowId: created.flowId,  expectedRevision: created.revision,  currentStep: "await-human-reply",  waitJson: { kind: "reply", channel: "telegram" },});

Use bindSession({ sessionKey, requesterOrigin }) quando você já tiver uma chave de sessão confiável do OpenClaw da sua própria camada de vinculação. Não vincule a partir de entrada bruta do usuário.

Síntese de texto para fala.

// Standard TTSconst clip = await api.runtime.tts.textToSpeech({  text: "Hello from OpenClaw",  cfg: api.config,}); // Telephony-optimized TTSconst telephonyClip = await api.runtime.tts.textToSpeechTelephony({  text: "Hello from OpenClaw",  cfg: api.config,}); // List available voicesconst voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

Usa a configuração principal messages.tts e seleção de provedor. Retorna buffer de áudio PCM + taxa de amostragem.

Análise de imagem, áudio e vídeo.

// Describe an imageconst image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); // Transcribe audioconst { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  mime: "audio/ogg", // optional, for when MIME cannot be inferred}); // Describe a videoconst video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); // Generic file analysisconst result = await api.runtime.mediaUnderstanding.runFile({  filePath: "/tmp/inbound-file.pdf",  cfg: api.config,}); // Structured image extraction through a specific provider/model.// Include at least one image; text inputs are supplemental context.const evidence = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.5",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Prefer the printed total over handwritten notes." },  ],  instructions: "Extract vendor, total, and searchable tags.",  schemaName: "receipt.evidence",  jsonSchema: {    type: "object",    properties: {      vendor: { type: "string" },      total: { type: "number" },      tags: { type: "array", items: { type: "string" } },    },    required: ["vendor", "total"],  },  cfg: api.config,});

Retorna { text: undefined } quando nenhuma saída é produzida (por exemplo, entrada ignorada).

Geração de imagens.

const result = await api.runtime.imageGeneration.generate({  prompt: "A robot painting a sunset",  cfg: api.config,}); const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

Pesquisa na web.

const providers = api.runtime.webSearch.listProviders({ config: api.config }); const result = await api.runtime.webSearch.search({  config: api.config,  args: { query: "OpenClaw plugin SDK", count: 5 },});

Utilitários de mídia de baixo nível.

const webMedia = await api.runtime.media.loadWebMedia(url);const mime = await api.runtime.media.detectMime(buffer);const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);const metadata = await api.runtime.media.getImageMetadata(filePath);const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });const terminalQr = await api.runtime.media.renderQrTerminal("https://openclaw.ai");const pngQr = await api.runtime.media.renderQrPngBase64("https://openclaw.ai", {  scale: 6, // 1-12  marginModules: 4, // 0-16});const pngQrDataUrl = await api.runtime.media.renderQrPngDataUrl("https://openclaw.ai");const tmpRoot = resolvePreferredOpenClawTmpDir();const pngQrFile = await api.runtime.media.writeQrPngTempFile("https://openclaw.ai", {  tmpRoot,  dirPrefix: "my-plugin-qr-",  fileName: "qr.png",});

Snapshot atual da configuração de runtime e gravações transacionais de configuração. Prefira a configuração que já foi passada para o caminho de chamada ativo; use current() apenas quando o manipulador precisar diretamente do snapshot do processo.

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

mutateConfigFile(...) e replaceConfigFile(...) retornam um valor followUp, por exemplo { mode: "restart", requiresRestart: true, reason }, que registra a intenção do escritor sem tirar o controle de reinicialização do gateway.

Utilitários no nível do sistema.

await api.runtime.system.enqueueSystemEvent(event);api.runtime.system.requestHeartbeat({  source: "other",  intent: "event",  reason: "plugin-event",});api.runtime.system.requestHeartbeatNow({ reason: "plugin-event" }); // Deprecated compatibility alias.const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);const hint = api.runtime.system.formatNativeDependencyHint(pkg);

runCommandWithTimeout(...) retorna stdout e stderr capturados, contagens opcionais de truncamento, code, signal, killed, termination e noOutputTimedOut. Resultados de timeout e timeout sem saída relatam code: 124 quando o processo filho não fornece um código de saída diferente de zero. Saídas por sinal sem timeout ainda podem retornar code: null, então use termination e noOutputTimedOut para distinguir motivos de timeout.

Assinaturas de eventos.

api.runtime.events.onAgentEvent((event) => {  /* ... */});api.runtime.events.onSessionTranscriptUpdate((update) => {  /* ... */});

Registro em log.

const verbose = api.runtime.logging.shouldLogVerbose();const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });

Resolução de autenticação de modelo e provedor.

const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({  provider: "openai",  cfg,});

Resolução do diretório de estado e armazenamento chaveado com suporte em SQLite.

const stateDir = api.runtime.state.resolveStateDir(process.env);const store = api.runtime.state.openKeyedStore<MyRecord>({  namespace: "my-feature",  maxEntries: 200,  defaultTtlMs: 15 * 60_000,}); await store.register("key-1", { value: "hello" });const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });const value = await store.lookup("key-1");await store.consume("key-1");await store.clear();

Armazenamentos chaveados sobrevivem a reinicializações e são isolados pelo id do plugin vinculado ao runtime. Use registerIfAbsent(...) para reivindicações atômicas de deduplicação: ele retorna true quando a chave estava ausente ou expirada e foi registrada, ou false quando um valor ativo já existe sem sobrescrever seu valor, horário de criação ou TTL. Limites: maxEntries por namespace, 6.000 linhas ativas por plugin, valores JSON abaixo de 64 KB e expiração TTL opcional. Quando uma gravação excederia o limite de linhas do plugin, o runtime pode remover as linhas ativas mais antigas do namespace em gravação; namespaces irmãos não são removidos nessa gravação, e a gravação ainda falha se o namespace não puder liberar linhas suficientes.

Fábricas de ferramentas de memória e CLI.

const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);api.runtime.tools.registerMemoryCli(/* ... */);

Auxiliares de runtime específicos de canal (disponíveis quando um plugin de canal é carregado).

api.runtime.channel.media é a superfície preferida para downloads e armazenamento de mídia de canal:

const saved = await api.runtime.channel.media.saveRemoteMedia({  url,  subdir: "inbound",  maxBytes,  filePathHint: fileName,});

Use saveRemoteMedia(...) quando uma URL remota deve se tornar mídia do OpenClaw. Use saveResponseMedia(...) quando o plugin já buscou uma Response com autenticação, redirecionamento ou tratamento de lista de permissões próprios do plugin. Use readRemoteMediaBuffer(...) somente quando o plugin precisar de bytes brutos para inspeção, transformações, descriptografia ou reenvio. fetchRemoteMedia(...) permanece como um alias de compatibilidade obsoleto para readRemoteMediaBuffer(...).

api.runtime.channel.mentions é a superfície compartilhada de política de menções de entrada para plugins de canal empacotados que usam injeção de runtime:

const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {  mentionRegexes,  mentionPatterns,}); const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({  facts: {    canDetectMention: true,    wasMentioned: mentionMatch.matched,    implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(      "reply_to_bot",      isReplyToBot,    ),  },  policy: {    isGroup,    requireMention,    allowTextCommands,    hasControlCommand,    commandAuthorized,  },});

Auxiliares de menção disponíveis:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions intencionalmente não expõe os auxiliares de compatibilidade resolveMentionGating* mais antigos. Prefira o caminho normalizado { facts, policy }.