Langsung ke konten utama

Helper Runtime Plugin

Referensi untuk objek api.runtime yang disuntikkan ke setiap plugin selama pendaftaran. Gunakan helper ini alih-alih mengimpor internal host secara langsung.
Mencari panduan langkah demi langkah? Lihat Channel Plugins atau Provider Plugins untuk panduan langkah demi langkah yang menunjukkan helper ini dalam konteks.
register(api) {
  const runtime = api.runtime;
}

Namespace runtime

api.runtime.agent

Identitas agen, direktori, dan pengelolaan sesi.
// Resolve working directory agen
const agentDir = api.runtime.agent.resolveAgentDir(cfg);

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

// Dapatkan identitas agen
const identity = api.runtime.agent.resolveAgentIdentity(cfg);

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

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

// Pastikan workspace ada
await api.runtime.agent.ensureAgentWorkspace(cfg);

// Jalankan agen Pi tertanam
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),
});
Helper session store berada di bawah 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

Konstanta model dan provider default:
const model = api.runtime.agent.defaults.model; // misalnya "anthropic/claude-sonnet-4-6"
const provider = api.runtime.agent.defaults.provider; // misalnya "anthropic"

api.runtime.subagent

Luncurkan dan kelola eksekusi subagent di latar belakang.
// Mulai eksekusi subagent
const { runId } = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai", // override opsional
  model: "gpt-4.1-mini", // override opsional
  deliver: false,
});

// Tunggu hingga selesai
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });

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

// Hapus sesi
await api.runtime.subagent.deleteSession({
  sessionKey: "agent:main:subagent:search-helper",
});
Override model (provider/model) memerlukan opt-in operator melalui plugins.entries.<id>.subagent.allowModelOverride: true di config. Plugin tidak tepercaya tetap dapat menjalankan subagent, tetapi permintaan override ditolak.

api.runtime.taskFlow

Ikat runtime Task Flow ke session key OpenClaw yang ada atau konteks tool tepercaya, lalu buat dan kelola Task Flow tanpa meneruskan owner di setiap panggilan.
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" },
});
Gunakan bindSession({ sessionKey, requesterOrigin }) saat Anda sudah memiliki session key OpenClaw tepercaya dari binding layer Anda sendiri. Jangan mengikat dari input pengguna mentah.

api.runtime.tts

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

// TTS yang dioptimalkan untuk telepon
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

// Daftar suara yang tersedia
const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});
Menggunakan konfigurasi core messages.tts dan pemilihan provider. Mengembalikan buffer audio PCM
  • sample rate.

api.runtime.mediaUnderstanding

Analisis gambar, audio, dan video.
// Deskripsikan gambar
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

// Transkripsikan audio
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  mime: "audio/ogg", // opsional, saat MIME tidak dapat disimpulkan
});

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

// Analisis file generik
const result = await api.runtime.mediaUnderstanding.runFile({
  filePath: "/tmp/inbound-file.pdf",
  cfg: api.config,
});
Mengembalikan { text: undefined } saat tidak ada output yang dihasilkan (misalnya input dilewati).
api.runtime.stt.transcribeAudioFile(...) tetap ada sebagai alias kompatibilitas untuk api.runtime.mediaUnderstanding.transcribeAudioFile(...).

api.runtime.imageGeneration

Pembuatan gambar.
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

Pencarian 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

Utilitas media tingkat rendah.
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

Muat dan tulis config.
const cfg = await api.runtime.config.loadConfig();
await api.runtime.config.writeConfigFile(cfg);

api.runtime.system

Utilitas tingkat sistem.
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

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

api.runtime.logging

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

api.runtime.modelAuth

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

api.runtime.state

Resolusi direktori state.
const stateDir = api.runtime.state.resolveStateDir();

api.runtime.tools

Factory tool memory dan CLI.
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
api.runtime.tools.registerMemoryCli(/* ... */);

api.runtime.channel

Helper runtime khusus channel (tersedia saat plugin channel dimuat).

Menyimpan referensi runtime

Gunakan createPluginRuntimeStore untuk menyimpan referensi runtime agar dapat digunakan di luar callback 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");

// Di titik entri Anda
export default defineChannelPluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Example",
  plugin: myPlugin,
  setRuntime: store.setRuntime,
});

// Di file lain
export function getRuntime() {
  return store.getRuntime(); // melempar jika belum diinisialisasi
}

export function tryGetRuntime() {
  return store.tryGetRuntime(); // mengembalikan null jika belum diinisialisasi
}

Field api tingkat atas lainnya

Selain api.runtime, objek API juga menyediakan:
FieldTypeDescription
api.idstringid plugin
api.namestringnama tampilan plugin
api.configOpenClawConfigsnapshot config saat ini (snapshot runtime dalam memori yang aktif saat tersedia)
api.pluginConfigRecord<string, unknown>config khusus plugin dari plugins.entries.<id>.config
api.loggerPluginLoggerlogger dengan scope (debug, info, warn, error)
api.registrationModePluginRegistrationModemode pemuatan saat ini; "setup-runtime" adalah jendela startup/setup ringan sebelum entri penuh
api.resolvePath(input)(string) => stringresolve path relatif terhadap root plugin

Terkait