Use this file to discover all available pages before exploring further.

Plugin runtime helpers

Reference for the

text

api.runtime

object injected into every plugin during registration. Use these helpers instead of importing host internals directly.

Channel plugins

Step-by-step guide that uses these helpers in context for channel plugins.

Provider plugins

Step-by-step guide that uses these helpers in context for provider plugins.


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

Config Loading And Writes

Prefer config that was already passed into the active call path, for example

text

api.config

during registration or a

text

cfg

argument on channel/provider callbacks. This keeps one process snapshot flowing through the work instead of reparsing config on hot paths.

Use

text

api.runtime.config.current()

only when a long-lived handler needs the current process snapshot and no config was passed to that function. The returned value is readonly; clone or use a mutation helper before editing.

Tool factories receive

text

ctx.runtimeConfig

plus

text

ctx.getRuntimeConfig()

. Use the getter inside a long-lived tool's

text

execute

callback when config can change after the tool definition was created.

Persist changes with

text

api.runtime.config.mutateConfigFile(...)

text

api.runtime.config.replaceConfigFile(...)

. Each write must choose an explicit

text

afterWrite

policy:

text
afterWrite: { mode: "auto" }
lets the gateway reload planner decide.
text
afterWrite: { mode: "restart", reason: "..." }
forces a clean restart when the writer knows hot reload is unsafe.
text
afterWrite: { mode: "none", reason: "..." }
suppresses automatic reload/restart only when the caller owns the follow-up.

The mutation helpers return

text

afterWrite

plus a typed

text

followUp

summary so callers can log or test whether they requested a restart. The gateway still owns when that restart actually happens.

text

api.runtime.config.loadConfig()

and

text

api.runtime.config.writeConfigFile(...)

are deprecated compatibility helpers under

text

runtime-config-load-write

. They warn once at runtime, and remain available for old external plugins during the migration window. Bundled plugins must not use them; the config boundary guards fail if plugin code calls them or imports those helpers from plugin SDK subpaths.

For direct SDK imports, use the focused config subpaths instead of the broad

text

openclaw/plugin-sdk/config-runtime

compatibility barrel:

text

config-types

for types,

text

plugin-config-runtime

for already-loaded config assertions and plugin entry lookup,

text

runtime-config-snapshot

for current process snapshots, and

text

config-mutation

for writes. Bundled plugin tests should mock these focused subpaths directly instead of mocking the broad compatibility barrel.

Internal OpenClaw runtime code has the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. Successful mutation writes refresh the process runtime snapshot and advance its internal revision; long-lived caches should key off the runtime-owned cache key instead of serializing config locally. Long-lived runtime modules have a zero-tolerance scanner for ambient

text

loadConfig()

calls; use a passed

text

cfg

, a request

text

context.getRuntimeConfig()

, or

text

getRuntimeConfig()

at an explicit process boundary.

Provider and channel execution paths must use the active runtime config snapshot, not a file snapshot returned for config readback or editing. File snapshots preserve source values such as SecretRef markers for UI and writes; provider callbacks need the resolved runtime view. When a helper may be called with either the active source snapshot or the active runtime snapshot, route through

text

selectApplicableRuntimeConfig()

before reading credentials.

Runtime namespaces

Storing runtime references

Use

text

createPluginRuntimeStore

to store the runtime reference for use outside the

text

register

callback:

Create the store

```typescript} import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";


text
const store = createPluginRuntimeStore<PluginRuntime>({
  pluginId: "my-plugin",
  errorMessage: "my-plugin runtime not initialized",
});
```

Wire into the entry point

```typescript} export default defineChannelPluginEntry({ id: "my-plugin", name: "My Plugin", description: "Example", plugin: myPlugin, setRuntime: store.setRuntime, }); ```

Access from other files

```typescript} export function getRuntime() { return store.getRuntime(); // throws if not initialized }


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

note

Prefer `pluginId` for the runtime-store identity. The lower-level `key` form is for uncommon cases where one plugin intentionally needs more than one runtime slot.

Other top-level
text
`api`
fields

Beyond

text

api.runtime

, the API object also provides:

Plugin id. Plugin display name. Current config snapshot (active in-memory runtime snapshot when available). Plugin-specific config from `plugins.entries..config`. Scoped logger (`debug`, `info`, `warn`, `error`). Current load mode; `"setup-runtime"` is the lightweight pre-full-entry startup/setup window. Resolve a path relative to the plugin root.

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

OpenClaw Docs

Plugin runtime helpers

Channel plugins

Provider plugins

Config Loading And Writes

Runtime namespaces

Storing runtime references

Create the store

Wire into the entry point

Access from other files

note

Other top-level
text
`api`
fields

Related

OpenClaw Docs

Plugin runtime helpers

Channel plugins

Provider plugins

Config Loading And Writes

Runtime namespaces

Storing runtime references

Create the store

Wire into the entry point

Access from other files

note

Other top-level textCopyapi fields

Related

Other top-level
text
`api`
fields