Plugin runtime yardımcıları

Ajan kimliği, dizinler ve oturum yönetimi.

// 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(...), Plugin kodundan normal bir OpenClaw ajan turu başlatmak için tarafsız yardımcıdır. Kanal tarafından tetiklenen yanıtlarla aynı sağlayıcı/model çözümlemesini ve ajan-harness seçimini kullanır.

runEmbeddedPiAgent(...), mevcut Pluginler için kullanımdan kaldırılmış bir uyumluluk takma adı olarak kalır. Yeni kod runEmbeddedAgent(...) kullanmalıdır.

resolveThinkingPolicy(...), sağlayıcı/model tarafından desteklenen düşünme seviyelerini ve isteğe bağlı varsayılanı döndürür. Sağlayıcı Pluginleri, modele özgü profilin sahibi olan düşünme hook'ları üzerinden bunu yönetir; bu nedenle araç Pluginleri sağlayıcı listelerini içe aktarmak veya çoğaltmak yerine bu çalışma zamanı yardımcısını çağırmalıdır.

normalizeThinkingLevel(...), on, x-high veya extra high gibi kullanıcı metnini, çözümlenmiş ilkeye göre denetlemeden önce kanonik saklanan seviyeye dönüştürür.

Oturum deposu yardımcıları api.runtime.agent.session altındadır:

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

Oturum iş akışları için getSessionEntry(...), listSessionEntries(...), patchSessionEntry(...) veya upsertSessionEntry(...) tercih edin. Bu yardımcılar oturumları ajan/oturum kimliğine göre adresler; böylece Pluginler eski sessions.json depolama şekline bağımlı olmaz. Yalnızca meta veri yamaları oturum etkinliğini yenilememeliyse preserveActivity: true kullanın; replaceEntry: true değerini yalnızca callback eksiksiz bir girdi döndürdüğünde ve silinen alanların silinmiş kalması gerektiğinde kullanın.

Bir Plugin kalıcı bir oturum üzerinde iş başlattığında runWithWorkAdmission(...) kullanın. Callback arşivlenmiş veya eşzamanlı olarak değiştirilmiş oturumları reddeder, arşiv/sıfırlama/silme mutasyonlarını tamamlanma boyunca koordine tutar ve ajan çalıştırmasına iletilmesi gereken bir AbortSignal alır.

Transkript okuma ve yazma işlemleri için openclaw/plugin-sdk/session-transcript-runtime öğesini içe aktarın ve { agentId, sessionKey, sessionId } ile resolveSessionTranscriptIdentity(...), resolveSessionTranscriptTarget(...), readSessionTranscriptEvents(...), appendSessionTranscriptMessageByIdentity(...), publishSessionTranscriptUpdateByIdentity(...) veya withSessionTranscriptWriteLock(...) kullanın. Bu API'ler Pluginlerin bir transkripti tanımlamasına, olaylarını okumasına, iletiler eklemesine, güncellemeler yayımlamasına ve ilgili işlemleri aynı transkript yazma kilidi altında çalıştırmasına olanak tanır. sessionFile geçirmek, resolveSessionTranscriptLegacyFileTarget(...) kullanmak veya openclaw/plugin-sdk/agent-harness-runtime üzerinden düşük seviyeli appendSessionTranscriptMessage(...) / emitSessionTranscriptUpdate(...) içe aktarmak kullanımdan kaldırılmıştır; bu yollar yalnızca zaten etkin bir transkript artefaktı alan eski kodlar için mevcuttur.

loadSessionStore(...), saveSessionStore(...), updateSessionStore(...), resolveSessionFilePath(...) ve resolveAndPersistSessionFile(...), hâlâ bilinçli olarak eski tüm-depo veya transkript-dosyası şekline bağımlı olan Pluginler için kullanımdan kaldırılmış uyumluluk yardımcılarıdır. Yeni Plugin kodu bu yardımcıları kullanmamalıdır; mevcut çağıranlar da giriş yardımcılarına ve transkript kimliği yardımcılarına geçmelidir.

Varsayılan model ve sağlayıcı sabitleri:

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

Sağlayıcı iç bileşenlerini içe aktarmadan veya OpenClaw model/kimlik doğrulama/temel URL hazırlığını çoğaltmadan, ana makinenin sahip olduğu bir metin tamamlama çalıştırın.

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

Yardımcı, OpenClaw'ın yerleşik çalışma zamanı ile aynı basit tamamlama hazırlık yolunu ve ana makinenin sahip olduğu çalışma zamanı yapılandırma anlık görüntüsünü kullanır. Bağlam motorları oturuma bağlı bir llm.complete yeteneği alır; böylece model çağrıları etkin oturumun ajanını kullanır ve sessizce varsayılan ajana geri dönmez. Sonuç, sağlayıcı/model/ajan atfının yanı sıra mevcut olduğunda normalleştirilmiş token, önbellek ve tahmini maliyet kullanımını içerir.

Arka plan alt aracı çalıştırmalarını başlatın ve yönetin.

// 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(...), aynı plugin tarafından api.runtime.subagent.run(...) üzerinden oluşturulan oturumları silebilir. Rastgele kullanıcı veya operatör oturumlarını silmek yine de yönetici kapsamlı bir Gateway isteği gerektirir.

Bağlı düğümleri listeleyin ve Gateway tarafından yüklenen plugin kodundan veya plugin CLI komutlarından düğüm ana bilgisayar komutu çağırın. Bunu, bir plugin eşleştirilmiş bir cihazda yerel işi sahiplendiğinde kullanın; örneğin başka bir Mac'teki tarayıcı veya ses köprüsü.

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 içinde bu çalışma zamanı işlem içindedir. Plugin CLI komutlarında yapılandırılmış Gateway'i RPC üzerinden çağırır; böylece openclaw googlemeet recover-tab gibi komutlar terminalden eşleştirilmiş düğümleri inceleyebilir. Node komutları yine de normal Gateway düğüm eşleştirmesinden, komut izin listelerinden, plugin düğüm çağırma ilkelerinden ve düğüm yerel komut işlemeden geçer.

Tehlikeli düğüm ana bilgisayar komutları sunan plugin'ler api.registerNodeInvokePolicy(...) ile bir düğüm çağırma ilkesi kaydetmelidir. İlke, Gateway içinde komut izin listesi kontrollerinden sonra ve komut düğüme iletilmeden önce çalışır; böylece doğrudan node.invoke çağrıları ve daha üst düzey plugin araçları aynı yaptırım yolunu paylaşır.

Bir Task Flow çalışma zamanını mevcut bir OpenClaw oturum anahtarına veya güvenilir araç bağlamına bağlayın, ardından her çağrıda sahip iletmeden Task Flow'ları oluşturun ve yönetin.

Task Flow dayanıklı çok adımlı iş akışı durumunu izler. Bu bir zamanlayıcı değildir: gelecekteki uyandırmalar için Cron veya api.session.workflow.scheduleSessionTurn(...) kullanın, ardından bu iş akış durumu, alt görevler, beklemeler veya iptal gerektirdiğinde zamanlanmış turdan managedFlows kullanın.

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

Kendi bağlama katmanınızdan zaten güvenilir bir OpenClaw oturum anahtarınız olduğunda bindSession({ sessionKey, requesterOrigin }) kullanın. Ham kullanıcı girdisinden bağlamayın.

Metinden konuşmaya sentezi.

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

Çekirdek messages.tts yapılandırmasını ve sağlayıcı seçimini kullanır. PCM ses arabelleği + örnekleme hızı döndürür.

Görüntü, ses ve video analizi.

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

Çıktı üretilmediğinde (ör. atlanan girdi) { text: undefined } döndürür.

Görüntü oluşturma.

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

Web araması.

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

Düşük düzey medya yardımcıları.

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

Geçerli çalışma zamanı yapılandırma anlık görüntüsü ve işlemsel yapılandırma yazımları. Etkin çağrı yoluna zaten iletilmiş yapılandırmayı tercih edin; current() öğesini yalnızca işleyicinin işlem anlık görüntüsüne doğrudan ihtiyaç duyması durumunda kullanın.

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

mutateConfigFile(...) ve replaceConfigFile(...) bir followUp değeri döndürür; örneğin { mode: "restart", requiresRestart: true, reason }. Bu değer, yeniden başlatma denetimini Gateway'den almadan yazıcının niyetini kaydeder.

Sistem düzeyi yardımcılar.

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(...), yakalanan stdout ve stderr, isteğe bağlı kısaltma sayıları, code, signal, killed, termination ve noOutputTimedOut döndürür. Zaman aşımı ve çıktı olmama zaman aşımı sonuçları, alt süreç sıfır olmayan bir çıkış kodu sağlamadığında code: 124 bildirir. Zaman aşımı olmayan sinyal çıkışları yine de code: null döndürebilir; bu nedenle zaman aşımı nedenlerini ayırt etmek için termination ve noOutputTimedOut kullanın.

Olay abonelikleri.

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

Günlük kaydı.

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

Model ve sağlayıcı kimlik doğrulama çözümlemesi.

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

Durum dizini çözümlemesi ve SQLite destekli anahtarlı depolama.

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

Anahtarlı depolar yeniden başlatmalardan sonra korunur ve çalışma zamanına bağlı Plugin kimliğine göre yalıtılır. Atomik tekilleştirme hak talepleri için registerIfAbsent(...) kullanın: anahtar eksikse veya süresi dolmuşsa ve kaydedildiyse true, canlı bir değer zaten varsa ve değerinin, oluşturulma zamanının veya TTL'sinin üzerine yazılmadıysa false döndürür. Sınırlar: ad alanı başına maxEntries, Plugin başına 6.000 canlı satır, 64 KB altındaki JSON değerleri ve isteğe bağlı TTL süresi dolması. Bir yazma işlemi Plugin satır sınırını aşacaksa çalışma zamanı, yazılan ad alanındaki en eski canlı satırları çıkarabilir; kardeş ad alanları bu yazma için çıkarılmaz ve ad alanı yeterli satır boşaltamazsa yazma yine başarısız olur.

Bellek aracı fabrikaları ve CLI.

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

Kanala özgü çalışma zamanı yardımcıları (bir kanal Plugin'i yüklendiğinde kullanılabilir).

api.runtime.channel.media, kanal medya indirmeleri ve depolama için tercih edilen yüzeydir:

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

Uzak bir URL'nin OpenClaw medyasına dönüşmesi gerektiğinde saveRemoteMedia(...) kullanın. Plugin, Plugin'e ait kimlik doğrulama, yönlendirme veya izin listesi işleme ile zaten bir Response getirdiyse saveResponseMedia(...) kullanın. readRemoteMediaBuffer(...) yalnızca Plugin'in inceleme, dönüştürme, şifre çözme veya yeniden yükleme için ham baytlara ihtiyacı olduğunda kullanın. fetchRemoteMedia(...), readRemoteMediaBuffer(...) için kullanımdan kaldırılmış bir uyumluluk takma adı olarak kalır.

api.runtime.channel.mentions, çalışma zamanı enjeksiyonu kullanan paketlenmiş kanal Plugin'leri için paylaşılan gelen bahsetme ilkesi yüzeyidir:

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

Kullanılabilir bahsetme yardımcıları:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions, eski resolveMentionGating* uyumluluk yardımcılarını kasıtlı olarak açığa çıkarmaz. Normalleştirilmiş { facts, policy } yolunu tercih edin.