ابزارهای کمکی زمان اجرای Plugin

هویت agent، directoryها، و مدیریت session.

// Resolve the agent's working directory
const agentDir = api.runtime.agent.resolveAgentDir(cfg);

// Resolve agent workspace
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);

// Get agent identity
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

// Get default thinking level
const thinking = api.runtime.agent.resolveThinkingDefault({
  cfg,
  provider,
  model,
});

// Validate a user-provided thinking level against the active provider profile
const 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 timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

// Ensure workspace exists
await api.runtime.agent.ensureAgentWorkspace(cfg);

// Run an embedded agent turn
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedAgent({
  sessionId: "my-plugin:task-1",
  runId: crypto.randomUUID(),
  sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
  prompt: "Summarize the latest changes",
  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});

runEmbeddedAgent(...) helper خنثی برای شروع یک turn معمولی OpenClaw agent از کد plugin است. از همان resolution provider/model و انتخاب agent-harness استفاده می‌کند که replyهای channel-triggered استفاده می‌کنند.

runEmbeddedPiAgent(...) به‌عنوان alias سازگاری باقی می‌ماند.

resolveThinkingPolicy(...) سطح‌های thinking پشتیبانی‌شدهٔ provider/model و default اختیاری را برمی‌گرداند. provider pluginها profile اختصاصی مدل را از طریق hookهای thinking خود مالک هستند، بنابراین tool pluginها باید به‌جای import یا duplicate کردن فهرست‌های provider، این helper runtime را فراخوانی کنند.

normalizeThinkingLevel(...) متن کاربر مانند on، x-high، یا extra high را پیش از بررسی آن در برابر policy resolve‌شده، به سطح ذخیره‌شدهٔ canonical تبدیل می‌کند.

helperهای session store زیر api.runtime.agent.session هستند:

const storePath = api.runtime.agent.session.resolveStorePath(cfg);
const store = api.runtime.agent.session.loadSessionStore(storePath);
await api.runtime.agent.session.updateSessionStore(storePath, (nextStore) => {
  // Patch one entry without replacing the whole file from stale state.
  nextStore[sessionKey] = { ...nextStore[sessionKey], thinkingLevel: "high" };
});
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);

برای writeهای runtime، updateSessionStore(...) یا updateSessionStoreEntry(...) را ترجیح دهید. آن‌ها از مسیر writer session-store متعلق به Gateway عبور می‌کنند، updateهای همزمان را حفظ می‌کنند، و hot cache را دوباره استفاده می‌کنند. saveSessionStore(...) برای سازگاری و rewriteهای سبک maintenance آفلاین همچنان در دسترس می‌ماند.

ثابت‌های default model و provider:

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

اجرای subagentهای پس‌زمینه را launch و مدیریت کنید.

// Start a subagent run
const { 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 completion
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// Read session messages
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// Delete a session
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});

deleteSession(...) می‌تواند sessionهایی را حذف کند که همان plugin از طریق api.runtime.subagent.run(...) ساخته است. حذف sessionهای دلخواه کاربر یا اپراتور همچنان به یک درخواست Gateway با scope ادمین نیاز دارد.

nodeهای متصل را فهرست کنید و یک command میزبان node را از کد plugin بارگذاری‌شده در Gateway یا از commandهای CLI plugin فراخوانی کنید. زمانی از این استفاده کنید که یک plugin مالک کار محلی روی دستگاه paired باشد، برای مثال browser یا audio bridge روی 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 این runtime درون‌فرایندی است. در commandهای CLI plugin، Gateway پیکربندی‌شده را از طریق RPC فراخوانی می‌کند، بنابراین commandهایی مانند openclaw googlemeet recover-tab می‌توانند nodeهای paired را از terminal بررسی کنند. commandهای Node همچنان از مسیر pairing معمول node در Gateway، allowlistهای command، policyهای node-invoke plugin، و handling command محلی node عبور می‌کنند.

pluginهایی که commandهای خطرناک میزبان node را expose می‌کنند باید یک policy node-invoke با api.registerNodeInvokePolicy(...) ثبت کنند. policy پس از بررسی‌های allowlist command و پیش از forward شدن command به node در Gateway اجرا می‌شود، بنابراین فراخوانی‌های مستقیم node.invoke و ابزارهای سطح‌بالاتر plugin مسیر enforcement یکسانی را به اشتراک می‌گذارند.

یک runtime Task Flow را به یک session key موجود OpenClaw یا context ابزار trusted متصل کنید، سپس بدون پاس دادن owner در هر فراخوانی، Task Flowها را بسازید و مدیریت کنید.

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 }) استفاده کنید که از لایهٔ binding خودتان یک session key trusted OpenClaw در اختیار دارید. از input خام کاربر bind نکنید.

synthesis متن به گفتار.

// Standard TTS
const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// Telephony-optimized TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// List available voices
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

از پیکربندی core messages.tts و انتخاب provider استفاده می‌کند. audio buffer PCM به‌همراه sample rate برمی‌گرداند.

تحلیل image، audio، و video.

// Describe an image
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// Transcribe audio
const { 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 video
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

// Generic file analysis
const result = await api.runtime.mediaUnderstanding.runFile({
  filePath: "/tmp/inbound-file.pdf",
  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",
});

تصویر لحظه‌ای پیکربندی runtime فعلی و نوشتن‌های تراکنشی پیکربندی. پیکربندی‌ای را ترجیح دهید که از قبل به مسیر فراخوانی فعال پاس داده شده است؛ فقط زمانی از current() استفاده کنید که handler مستقیماً به تصویر لحظه‌ای فرایند نیاز دارد.

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 }، که قصد نویسنده را بدون گرفتن کنترل restart از 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);

اشتراک‌های رویداد.

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

تشخیص احراز هویت مدل و provider.

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

تشخیص دایرکتوری state و ذخیره‌سازی کلیددار مبتنی بر 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();

ذخیره‌گاه‌های کلیددار پس از restart باقی می‌مانند و با شناسه Plugin متصل به runtime ایزوله می‌شوند. برای ادعاهای dedupe اتمیک از registerIfAbsent(...) استفاده کنید: وقتی کلید وجود نداشته یا منقضی شده و ثبت شده باشد true برمی‌گرداند، یا وقتی یک مقدار زنده از قبل وجود دارد، بدون بازنویسی مقدار، زمان ایجاد یا TTL آن، false برمی‌گرداند. محدودیت‌ها: maxEntries برای هر namespace، ۱٬۰۰۰ ردیف زنده برای هر Plugin، مقادیر JSON کمتر از ۶۴KB، و انقضای TTL اختیاری.

کارخانه‌های ابزار حافظه و CLI.

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

helperهای runtime مخصوص کانال (وقتی یک Plugin کانال بارگذاری شده باشد در دسترس‌اند).

api.runtime.channel.mentions سطح مشترک سیاست mention ورودی برای Pluginهای کانال همراه‌شده‌ای است که از runtime injection استفاده می‌کنند:

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

helperهای mention موجود:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions عمداً helperهای سازگاری قدیمی‌تر resolveMentionGating* را expose نمی‌کند. مسیر نرمال‌شده { facts, policy } را ترجیح دهید.