Skip to main content

​
Plugin Runtime Helpers

在註冊期間注入每個外掛的 api.runtime 物件的參考。使用這些輔助函式，而不是直接 import 主機內部。
在找實作指南？ 參考 Channel 外掛 或 Provider 外掛，他們有逐步指南，展示這些輔助函式的實際使用。
register(api) {
  const runtime = api.runtime;
}

​
Runtime namespace

​
api.runtime.agent

Agent 身分、目錄與工作階段管理。 
// 解析 agent 的工作目錄
const agentDir = api.runtime.agent.resolveAgentDir(cfg);

// 解析 agent 工作區
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);

// 取得 agent 身分
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

// 取得預設 thinking 等級
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);

// 取得 agent 逾時
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);

// 確保工作區存在
await api.runtime.agent.ensureAgentWorkspace(cfg);

// 執行嵌入式 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: "總結最新的變更",
  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
});
Session store 輔助函式 在 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

預設模型與 provider 常數： 
const model = api.runtime.agent.defaults.model; // 例如 "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // 例如 "anthropic"

​
api.runtime.subagent

啟動與管理背景 subagent 執行。 
// 啟動 subagent 執行
const { runId } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "將此查詢擴展為專注的後續搜尋。",
  provider: "openai", // 可選覆蓋
  model: "gpt-4.1-mini", // 可選覆蓋
  deliver: false,
});

// 等待完成
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

// 讀取工作階段訊息
const { messages } = await api.runtime.subagent.getSessionMessages({
  sessionKey: "agent:main:subagent:search-helper",
  limit: 10,
});

// 刪除工作階段
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});
模型覆蓋（provider/model）需要操作者透過 config 中的 plugins.entries.<id>.subagent.allowModelOverride: true 選擇加入。不受信任的外掛仍可執行 subagent，但覆蓋請求會被拒絕。

​
api.runtime.tts

文字轉語音合成。 
// 標準 TTS
const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// 電話優化 TTS
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// 列出可用語音
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});
使用核心 messages.tts 設定與 provider 選擇。傳回 PCM audio buffer + sample rate。

​
api.runtime.mediaUnderstanding

影像、音訊與影片分析。 
// 描述影像
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// 轉錄音訊
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  mime: "audio/ogg", // 可選，當無法推斷 MIME 時使用
});

// 描述影片
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

// 泛用檔案分析
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: "一個機器人繪製日落",
  cfg: api.config,
});

const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });

​
api.runtime.webSearch

網路搜尋。 
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

低階 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

Event 訂閱。 
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

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

​
api.runtime.state

State 目錄解析。 
const stateDir = api.runtime.state.resolveStateDir();

​
api.runtime.tools

Memory tool factories 與 CLI。 
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

​
api.runtime.channel

Channel 特定 runtime 輔助函式（當 channel 外掛載入時可用）。

​
儲存 runtime 參考

使用 createPluginRuntimeStore 來儲存 runtime 參考，供 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 未初始化");

// 在妳的進入點
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "範例",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

// 在其他檔案
export function getRuntime() {
  return store.getRuntime(); // 未初始化時拋出
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // 未初始化時傳回 null
}

​
其他頂層 api 欄位

除了 api.runtime，API 物件也提供：
欄位型別說明
api.idstring外掛 id
api.namestring外掛顯示名稱
api.configOpenClawConfig目前 config 快照
api.pluginConfigRecord<string, unknown>外掛特定 config，來自 plugins.entries.<id>.config
api.loggerPluginLogger範疇化 logger（debug, info, warn, error）
api.registrationModePluginRegistrationMode"full"、"setup-only" 或 "setup-runtime"
api.resolvePath(input)(string) => string解析相對於外掛根的路徑

​
相關