Các trình trợ giúp thời gian chạy của Plugin

Danh tính agent, thư mục và quản lý phiên.

// 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(...) là helper trung lập để bắt đầu một lượt agent OpenClaw bình thường từ mã Plugin. Nó dùng cùng cơ chế resolve nhà cung cấp/mô hình và lựa chọn agent-harness như các phản hồi được kích hoạt bởi kênh.

runEmbeddedPiAgent(...) vẫn là alias tương thích.

resolveThinkingPolicy(...) trả về các mức suy nghĩ được hỗ trợ của nhà cung cấp/mô hình và mặc định tùy chọn. Plugin nhà cung cấp sở hữu profile theo mô hình thông qua các hook thinking của chúng, vì vậy Plugin công cụ nên gọi helper runtime này thay vì import hoặc sao chép danh sách nhà cung cấp.

normalizeThinkingLevel(...) chuyển văn bản người dùng như on, x-high, hoặc extra high sang mức được lưu chuẩn tắc trước khi kiểm tra nó với policy đã resolve.

Các helper kho phiên nằm dưới 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);

Ưu tiên updateSessionStore(...) hoặc updateSessionStoreEntry(...) cho thao tác ghi runtime. Chúng đi qua writer kho phiên do Gateway sở hữu, giữ lại các cập nhật đồng thời và tái sử dụng hot cache. saveSessionStore(...) vẫn khả dụng để tương thích và các lần ghi lại kiểu bảo trì ngoại tuyến.

Hằng số mô hình và nhà cung cấp mặc định:

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

Khởi chạy và quản lý các lượt chạy subagent nền.

// 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(...) có thể xóa các phiên được tạo bởi cùng Plugin thông qua api.runtime.subagent.run(...). Xóa phiên tùy ý của người dùng hoặc operator vẫn cần request Gateway có phạm vi admin.

Liệt kê các Node đã kết nối và gọi một lệnh node-host từ mã Plugin được Gateway tải hoặc từ lệnh CLI của Plugin. Dùng mục này khi một Plugin sở hữu công việc cục bộ trên thiết bị đã ghép đôi, ví dụ một browser hoặc audio bridge trên một máy Mac khác.

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

Bên trong Gateway, runtime này chạy trong tiến trình. Trong lệnh CLI của Plugin, nó gọi Gateway đã cấu hình qua RPC, vì vậy các lệnh như openclaw googlemeet recover-tab có thể kiểm tra Node đã ghép đôi từ terminal. Lệnh Node vẫn đi qua cơ chế ghép đôi Node Gateway bình thường, allowlist lệnh, policy node-invoke của Plugin và xử lý lệnh cục bộ trên Node.

Plugin phơi bày lệnh node-host nguy hiểm nên đăng ký policy node-invoke bằng api.registerNodeInvokePolicy(...). Policy chạy trong Gateway sau các kiểm tra allowlist lệnh và trước khi lệnh được chuyển tiếp đến Node, vì vậy các lời gọi node.invoke trực tiếp và công cụ Plugin cấp cao hơn dùng chung cùng đường dẫn thực thi.

Gắn runtime Task Flow vào một khóa phiên OpenClaw hiện có hoặc ngữ cảnh công cụ đáng tin cậy, rồi tạo và quản lý Task Flow mà không cần truyền owner trên mọi lời gọi.

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

Dùng bindSession({ sessionKey, requesterOrigin }) khi bạn đã có khóa phiên OpenClaw đáng tin cậy từ lớp binding của chính bạn. Đừng bind từ input thô của người dùng.

Tổng hợp văn bản thành giọng nói.

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

Dùng cấu hình messages.tts lõi và lựa chọn nhà cung cấp. Trả về buffer âm thanh PCM + sample rate.

Phân tích hình ảnh, âm thanh và 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,
});

Trả về { text: undefined } khi không tạo ra đầu ra nào (ví dụ: đầu vào bị bỏ qua).

Tạo hình ảnh.

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

Tìm kiếm 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 },
});

Tiện ích media cấp thấp.

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

Ảnh chụp cấu hình runtime hiện tại và ghi cấu hình theo giao dịch. Ưu tiên cấu hình đã được truyền vào đường dẫn lệnh gọi đang hoạt động; chỉ dùng current() khi trình xử lý cần trực tiếp ảnh chụp của tiến trình.

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

mutateConfigFile(...) và replaceConfigFile(...) trả về một giá trị followUp, ví dụ { mode: "restart", requiresRestart: true, reason }, ghi lại ý định của trình ghi mà không lấy quyền kiểm soát khởi động lại khỏi gateway.

Tiện ích cấp hệ thống.

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

Đăng ký theo dõi sự kiện.

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

Ghi log.

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

Phân giải xác thực model và provider.

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

Phân giải thư mục trạng thái và lưu trữ theo khóa dựa trên 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();

Kho lưu trữ theo khóa vẫn tồn tại sau khi khởi động lại và được cô lập theo id Plugin gắn với runtime. Dùng registerIfAbsent(...) cho các yêu cầu chống trùng lặp nguyên tử: hàm này trả về true khi khóa bị thiếu hoặc đã hết hạn và được đăng ký, hoặc false khi một giá trị còn hiệu lực đã tồn tại mà không ghi đè giá trị, thời điểm tạo hoặc TTL của nó. Giới hạn: maxEntries cho mỗi namespace, 1.000 hàng còn hiệu lực cho mỗi Plugin, giá trị JSON dưới 64KB và tùy chọn hết hạn TTL.

Factory công cụ bộ nhớ và CLI.

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

Helper runtime theo kênh (có sẵn khi Plugin kênh được tải).

api.runtime.channel.mentions là bề mặt chính sách nhắc đến đầu vào dùng chung cho các Plugin kênh được đóng gói sử dụng cơ chế chèn 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,
  },
});

Các helper nhắc đến có sẵn:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

api.runtime.channel.mentions cố ý không hiển thị các helper tương thích resolveMentionGating* cũ hơn. Ưu tiên đường dẫn { facts, policy } đã chuẩn hóa.