Plugin runtime helpers

Reference for the live api.runtime object available during "full", "discovery", "tool-discovery", and "setup-runtime" registration. During "cli-metadata" and "setup-only" registration, runtime capabilities are intentionally unavailable: accessing one throws an error naming the plugin and mode. Defer runtime access out of register() or, for root CLI commands, declare cliCommands in the plugin manifest. Use runtime helpers instead of importing host internals directly.

register(api) {  const runtime = api.runtime;}

api.runtime.version is the current OpenClaw product version, sourced from the shared version resolver so plugins see the same value the CLI reports.

What each page covers

• Config and utilities — runtime config reads and writes, plus the shared process, error, and model-picker utilities.
• Agent and sessions — agent identity, directories, session store, transcripts, and sandbox authority.
• Model helpers — host-owned completions, model-selection policy, and provider auth resolution.
• Background work — hook agent turns, subagent runs, and Task Flow record binding.
• Gateway and nodes — in-process Gateway requests, paired node invocation, and Gateway service events.
• Media helpers — speech, media understanding, image/video/music generation, web search, and media utilities.
• State and system — config snapshot, SQLite-backed plugin state, system utilities, events, and logging.
• Channel helpers — channel-specific runtime helper groups for chunking, routing, pairing, media, and mentions.

Runtime namespaces

Every api.runtime namespace and the page that documents it.

Storing runtime references

Use createPluginRuntimeStore to store the runtime reference for use outside the register callback:

import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; const store = createPluginRuntimeStore<PluginRuntime>({  pluginId: "my-plugin",  errorMessage: "my-plugin runtime not initialized",});

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; // `myPlugin` is your own `ChannelPlugin` object and `store` is the store// created in the previous step; neither is an SDK export.export default defineChannelPluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Example",  plugin: myPlugin,  setRuntime: store.setRuntime,});

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

Other top-level api fields

Beyond api.runtime, the API object also provides:

Where each section moved

Every section heading and namespace anchor from the previous single-page version keeps its anchor here, so an existing link such as /plugins/sdk-runtime#api-runtime-subagent still resolves. Each entry points at the page that now holds the content.

• Config loading and writes
• Reusable runtime utilities
• Stage timing diagnostics
• Plugin command runtime helpers
• Gateway service events
• api.runtime.agent
• api.runtime.agent.defaults
• api.runtime.llm
• api.runtime.gateway
• api.runtime.hooks
• api.runtime.subagent
• api.runtime.sandbox
• api.runtime.nodes
• api.runtime.tasks
• api.runtime.tts
• api.runtime.mediaUnderstanding
• api.runtime.imageGeneration
• api.runtime.videoGeneration
• api.runtime.musicGeneration
• api.runtime.webSearch
• api.runtime.media
• api.runtime.config
• api.runtime.system
• api.runtime.events
• api.runtime.logging
• api.runtime.modelConfig
• api.runtime.modelAuth
• api.runtime.state
• api.runtime.channel

Related

• Plugin internals — capability model and registry
• SDK entry points — definePluginEntry options
• SDK overview — subpath reference