Допоміжні засоби виконання Plugin

Ідентичність агента, каталоги та керування сеансами.

// 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(...) — нейтральний допоміжний засіб для запуску звичайного ходу агента OpenClaw з коду plugin. Він використовує те саме визначення provider/model і вибір agent-harness, що й відповіді, запущені каналом.

runEmbeddedPiAgent(...) залишається застарілим псевдонімом сумісності для наявних plugins. Новий код має використовувати runEmbeddedAgent(...).

resolveThinkingPolicy(...) повертає підтримувані provider/model рівні мислення та необов’язкове значення за замовчуванням. Provider plugins володіють профілем, специфічним для моделі, через свої thinking hooks, тому tool plugins мають викликати цей runtime helper замість імпорту або дублювання списків провайдерів.

normalizeThinkingLevel(...) перетворює користувацький текст, як-от on, x-high або extra high, на канонічний збережений рівень перед перевіркою за розв’язаною політикою.

Допоміжні засоби сховища сеансів розташовані в 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.  },);

Надавайте перевагу getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) або upsertSessionEntry(...) для робочих процесів сеансів. Ці допоміжні функції адресують сеанси за ідентичністю агента/сеансу, щоб plugins не залежали від застарілої форми сховища sessions.json. Використовуйте preserveActivity: true для виправлень лише метаданих, які не повинні оновлювати активність сеансу, і replaceEntry: true лише тоді, коли зворотний виклик повертає повний запис, а видалені поля мають залишатися видаленими.

Використовуйте runWithWorkAdmission(...), коли plugin починає роботу з персистентним сеансом. Зворотний виклик відхиляє архівовані або паралельно замінені сеанси, координує мутації архівування/скидання/видалення до завершення та отримує AbortSignal, який потрібно передати до запуску агента.

Для читання й запису транскриптів імпортуйте openclaw/plugin-sdk/session-transcript-runtime і використовуйте resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) або withSessionTranscriptWriteLock(...) з { agentId, sessionKey, sessionId }. Ці API дають plugins змогу ідентифікувати транскрипт, читати його події, додавати повідомлення, публікувати оновлення та виконувати пов’язані операції під тим самим блокуванням запису транскрипта. Передавання sessionFile, використання resolveSessionTranscriptLegacyFileTarget(...) або імпорт низькорівневих appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) з openclaw/plugin-sdk/agent-harness-runtime застаріли; ці шляхи існують лише для застарілого коду, який уже отримує активний артефакт транскрипта.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) і resolveAndPersistSessionFile(...) — це застарілі допоміжні функції сумісності для plugins, які досі навмисно залежать від застарілої форми всього сховища або файлу транскрипта. Новий код plugin не повинен використовувати ці допоміжні функції, а наявні виклики слід мігрувати на допоміжні функції записів і допоміжні функції ідентичності транскриптів.

Константи моделі та провайдера за замовчуванням:

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

Запустіть текстове доповнення, кероване хостом, без імпорту внутрішніх компонентів провайдера або дублювання підготовки моделі, автентифікації та базової URL OpenClaw.

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

Допоміжна функція використовує той самий шлях підготовки простого доповнення, що й вбудоване середовище виконання OpenClaw, а також знімок конфігурації середовища виконання, керований хостом. Рушії контексту отримують прив’язану до сеансу можливість llm.complete, тому виклики моделі використовують агента активного сеансу й не переходять непомітно до агента за замовчуванням. Результат містить атрибуцію провайдера/моделі/агента, а також нормалізоване використання токенів, кешу й оціненої вартості, коли це доступно.

Запускайте й керуйте фоновими запусками підлеглих агентів.

// 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(...) може видаляти сеанси, створені тим самим plugin через api.runtime.subagent.run(...). Видалення довільних сеансів користувача або оператора все ще потребує запиту Gateway з областю адміністратора.

Перелічуйте підключені вузли й викликайте команду хоста вузла з коду plugin, завантаженого Gateway, або з CLI-команд plugin. Використовуйте це, коли plugin володіє локальною роботою на спареному пристрої, наприклад мостом браузера або аудіо на іншому 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,});

Усередині Gateway це середовище виконання працює в процесі. У CLI-командах plugin воно викликає налаштований Gateway через RPC, тож команди на кшталт openclaw googlemeet recover-tab можуть перевіряти спарені вузли з термінала. Команди Node все одно проходять звичайне спарення вузлів Gateway, списки дозволених команд, політики виклику вузлів plugin і локальну обробку команд на вузлі.

Plugins, які відкривають небезпечні команди хоста вузла, мають зареєструвати політику виклику вузла через api.registerNodeInvokePolicy(...). Політика виконується в Gateway після перевірок списку дозволених команд і перед пересиланням команди на вузол, тож прямі виклики node.invoke і високорівневі інструменти plugin використовують той самий шлях застосування правил.

Прив’яжіть середовище виконання Task Flow до наявного ключа сеансу OpenClaw або довіреного контексту інструмента, а потім створюйте й керуйте Task Flows без передавання власника під час кожного виклику.

Task Flow відстежує довготривалий стан багатоетапного робочого процесу. Це не планувальник: використовуйте Cron або api.session.workflow.scheduleSessionTurn(...) для майбутніх пробуджень, а потім використовуйте managedFlows із запланованого ходу, коли цій роботі потрібні стан потоку, дочірні завдання, очікування або скасування.

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

Використовуйте bindSession({ sessionKey, requesterOrigin }), коли вже маєте довірений ключ сеансу OpenClaw із власного шару прив’язки. Не прив’язуйте з необробленого введення користувача.

Синтез мовлення з тексту.

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

Використовує основну конфігурацію messages.tts і вибір провайдера. Повертає аудіобуфер PCM + частоту дискретизації.

Аналіз зображень, аудіо та відео.

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

Повертає { text: undefined }, коли не створено жодного виводу (наприклад, введення пропущено).

Генерація зображень.

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

Вебпошук.

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

Низькорівневі медіаутиліти.

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

Поточний знімок конфігурації середовища виконання й транзакційні записи конфігурації. Надавайте перевагу конфігурації, яку вже передано в активний шлях виклику; використовуйте current() лише тоді, коли обробнику потрібен безпосередньо знімок процесу.

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

mutateConfigFile(...) і replaceConfigFile(...) повертають значення followUp, наприклад { mode: "restart", requiresRestart: true, reason }, яке записує намір записувача, не забираючи контроль перезапуску від gateway.

Утиліти системного рівня.

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(...) повертає захоплені stdout і stderr, необов’язкові лічильники обрізання, code, signal, killed, termination і noOutputTimedOut. Результати тайм-ауту й тайм-ауту без виводу повідомляють code: 124, коли дочірній процес не надає ненульового коду виходу. Виходи за сигналом без тайм-ауту все ще можуть повертати code: null, тому використовуйте termination і noOutputTimedOut, щоб розрізняти причини тайм-ауту.

Підписки на події.

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

Журналювання.

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

Розв’язання автентифікації моделі та провайдера.

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

Визначення каталогу стану та сховище ключів на основі 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();

Сховища ключів зберігаються після перезапусків і ізолюються за прив’язаним до середовища виконання id Plugin. Використовуйте registerIfAbsent(...) для атомарних заявок дедуплікації: він повертає true, коли ключ був відсутній або прострочений і зареєстрований, або false, коли активне значення вже існує без перезапису його значення, часу створення чи TTL. Обмеження: maxEntries на простір імен, 6 000 активних рядків на Plugin, JSON-значення менші за 64KB та необов’язкове завершення строку дії TTL. Коли запис перевищив би ліміт рядків Plugin, середовище виконання може витіснити найстаріші активні рядки з простору імен, у який виконується запис; суміжні простори імен для цього запису не витісняються, а запис усе одно завершується помилкою, якщо простір імен не може звільнити достатньо рядків.

Фабрики інструментів пам’яті та CLI.

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

Допоміжні засоби середовища виконання для каналів (доступні, коли завантажено Plugin каналу).

api.runtime.channel.media — рекомендована поверхня для завантаження та зберігання медіа каналу:

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

Використовуйте saveRemoteMedia(...), коли віддалена URL-адреса має стати медіа OpenClaw. Використовуйте saveResponseMedia(...), коли Plugin уже отримав Response із власною для Plugin обробкою автентифікації, переспрямування або списку дозволених адрес. Використовуйте readRemoteMediaBuffer(...) лише тоді, коли Plugin потрібні необроблені байти для інспекції, перетворень, розшифрування або повторного завантаження. fetchRemoteMedia(...) залишається застарілим сумісним псевдонімом для readRemoteMediaBuffer(...).

api.runtime.channel.mentions — спільна поверхня політики вхідних згадок для вбудованих plugins каналів, які використовують ін’єкцію середовища виконання:

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

Доступні допоміжні засоби для згадок:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions навмисно не відкриває старіші сумісні допоміжні засоби resolveMentionGating*. Надавайте перевагу нормалізованому шляху { facts, policy }.