Skip to main content

​
插件运行时辅助工具

这是对在注册期间注入到每个插件中的 api.runtime 对象的参考说明。请使用这些辅助工具，而不是直接导入宿主内部实现。
想看操作演示？ 请参阅 渠道插件 或 提供商插件 中的分步指南， 它们会结合上下文展示这些辅助工具的用法。
register(api) {
  const runtime = api.runtime;
}

​
运行时命名空间

​
api.runtime.agent

智能体身份、目录和会话管理。 
// 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);

// Get agent timeout
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

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

// Run an embedded Pi agent
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedPiAgent({
  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),
});
会话存储辅助工具 位于 api.runtime.agent.session 下： 
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
const store = api.runtime.agent.session.loadSessionStore(cfg);
await api.runtime.agent.session.saveSessionStore(cfg, store);
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);

​
api.runtime.agent.defaults

默认模型和提供商常量： 
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"

​
api.runtime.subagent

启动并管理后台 subagent 运行。 
// 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",
});
模型覆盖（provider/model）需要操作员在 config 中通过 plugins.entries.<id>.subagent.allowModelOverride: true 明确启用。 不受信任的插件仍然可以运行 subagent，但其覆盖请求会被拒绝。

​
api.runtime.taskFlow

将 Task Flow 运行时绑定到现有的 OpenClaw 会话键或受信任的工具上下文， 然后在每次调用时无需传入 owner，即可创建和管理 Task Flows。 
const taskFlow = api.runtime.taskFlow.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" },
});
当你已经从自己的绑定层获得一个受信任的 OpenClaw 会话键时，请使用 bindSession({ sessionKey, requesterOrigin })。不要从原始用户输入进行绑定。

​
api.runtime.tts

文本转语音合成。 
// 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,
});
使用核心 messages.tts 配置和提供商选择。返回 PCM 音频缓冲区和采样率。

​
api.runtime.mediaUnderstanding

图像、音频和视频分析。 
// 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 }。
api.runtime.stt.transcribeAudioFile(...) 仍保留为 api.runtime.mediaUnderstanding.transcribeAudioFile(...) 的兼容别名。

​
api.runtime.imageGeneration

图像生成。 
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 });

​
api.runtime.webSearch

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

​
api.runtime.media

底层媒体实用工具。 
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 });

​
api.runtime.config

Config 加载和写入。 
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);

​
api.runtime.system

系统级实用工具。 
await api.runtime.system.enqueueSystemEvent(event);
api.runtime.system.requestHeartbeatNow();
const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
const hint = api.runtime.system.formatNativeDependencyHint(pkg);

​
api.runtime.events

事件订阅。 
api.runtime.events.onAgentEvent((event) => {
  /* ... */
});
api.runtime.events.onSessionTranscriptUpdate((update) => {
  /* ... */
});

​
api.runtime.logging

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

​
api.runtime.modelAuth

模型和提供商凭证解析。 
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
  provider: "openai",
  cfg,
});

​
api.runtime.state

状态目录解析。 
const stateDir = api.runtime.state.resolveStateDir();

​
api.runtime.tools

内存工具工厂和 CLI。 
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

​
api.runtime.channel

渠道专用运行时辅助工具（在加载渠道插件时可用）。 api.runtime.channel.mentions 是供使用运行时注入的内置渠道插件共享的入站提及策略接口： 
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,
  },
});
可用的 mention 辅助工具包括：
  • buildMentionRegexes
  • matchesMentionPatterns
  • matchesMentionWithExplicit
  • implicitMentionKindWhen
  • resolveInboundMentionDecision
api.runtime.channel.mentions 有意不暴露较旧的 resolveMentionGating* 兼容辅助工具。请优先使用标准化的 { facts, policy } 路径。

​
存储运行时引用

使用 createPluginRuntimeStore 存储运行时引用，以便在 register 回调之外使用： 
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";

const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");

// In your entry point
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Example",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

// In other files
export function getRuntime() {
  return store.getRuntime(); // throws if not initialized
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // returns null if not initialized
}

​
其他顶层 api 字段

除 api.runtime 之外，API 对象还提供：
FieldTypeDescription
api.idstring插件 id
api.namestring插件显示名称
api.configOpenClawConfig当前 config 快照（可用时为活动的内存中运行时快照）
api.pluginConfigRecord<string, unknown>来自 plugins.entries.<id>.config 的插件专用 config
api.loggerPluginLogger作用域日志记录器（debug、info、warn、error）
api.registrationModePluginRegistrationMode当前加载模式；"setup-runtime" 是完整入口启动/设置前的轻量级窗口
api.resolvePath(input)(string) => string解析相对于插件根目录的路径

​
相关内容