# Plugin runtime Gateway and nodes > In-process Gateway requests, paired node invocation, and Gateway service events - 网址：https://funcoding.ai/agents/openclaw/plugins/sdk-runtime/gateway-and-nodes/ - 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/plugins/sdk-runtime/gateway-and-nodes --- Reach the Gateway and paired nodes from plugin code, and the events a long-lived Gateway service receives. Part of the [Plugin runtime helpers](https://funcoding.ai/agents/openclaw/plugins/sdk-runtime/) reference. ## Service scheduling Register a service with `apiVersion: 2` to require the host-owned `PluginServiceSchedulerV1` capability in its start and stop context: ```typescript api.registerService({ id: "catalog-refresh", apiVersion: 2, start({ scheduler }) { scheduler.schedule({ id: "refresh", delayMs: 0, everyMs: 60_000, run: () => refreshCatalog({ signal: scheduler.signal }), }); }, }); ``` Import `OpenClawPluginServiceV2`, `OpenClawPluginServiceContextV2`, and `PluginServiceSchedulerV1` from `openclaw/plugin-sdk/plugin-entry` when naming these contracts. Existing `OpenClawPluginService` and `OpenClawPluginServiceContext` types remain source-compatible; their scheduler field is optional. The Gateway supplies a scheduler to both service versions. `schedule` accepts either an absolute `atMs` or a relative `delayMs`. Job IDs belong to one scope: scheduling the same ID replaces its pending dispatch, while other services and child scopes can use the same ID independently. `mode: "earliest"` retains the earlier pending deadline. `everyMs` schedules the next run after the callback settles and coalesces missed periods; callbacks must return their asynchronous work so retirement can join it. Errors are reported by the host scheduler. The returned handle's `cancel()` prevents future dispatch, and `stop()` also waits for that job's running callback. Use `scheduler.scope()` for a shorter connection or watcher lifetime. Its `beginClose()` closes admission, aborts its signal, and cancels pending work; `await stop()` also joins running work and all descendants. Closing a child does not stop its parent or siblings. Closing the service closes all its child scopes. Retained `schedule` and `scope` functions throw after closure. Do not await a scope's `stop()` from one of its own running callbacks. The host first closes scheduling admission and signals cancellation, then invokes the service's stop hook. Retirement waits for both that hook and scheduled work. Plugins retain ownership of reconnection policy, sockets, watchers, durable flush ordering, and delivery custody. Stop transports and flush pending delivery in the owner's required order, then join its child scope before closing resources used by that work. Pass the lifetime signal to operations that support cancellation, and finish admitted writes before returning. Scheduling creates no durable jobs and changes no stored config or state; an update requires no state migration. Channel Gateway adapters opt in with `apiVersion: 2`. Their `startAccount` and `stopAccount` callbacks receive `ChannelGatewayContextV2`, including the required account scheduler. Import that context and `ChannelGatewayAdapterV2` from `openclaw/plugin-sdk/channel-contract`. Existing version 1 adapters keep an optional scheduler field and continue to work unchanged. The host supplies the same capability to both versions and joins scheduled work before retiring an account. Bundled plugin timer migrations can adopt it independently. `ChannelPlugin` and `createChatChannelPlugin` default to the version 1 Gateway adapter, preserving existing declarations and manual calls. Use `ChannelPlugin` or the fourth `createChatChannelPlugin` type argument for a version 2 adapter. Inline `api.registerChannel` registrations infer the callback context from the adapter's `apiVersion`. Published factories whose older parameter contracts did not accept a scheduler use `resolvePluginServiceScheduler` from `openclaw/plugin-sdk/runtime` in their version 1 adapter, then delegate to their version 2 implementation. The resolver accepts an explicit handle or borrows the currently bound service, account, or executable CLI lifetime. It rejects missing or closed owners and never creates a root scheduler. New factories require the handle explicitly. CLI callbacks retain the scheduling owner captured when their command is registered. Timed callbacks run in the same plugin instance without inheriting the initiating request or operator authority. A command that serves a runtime must remain pending until that runtime closes; returning from the action lets the executable retire and join its scheduler before releasing the plugin. One-shot diagnostics exporters borrow the existing CLI SDK host scheduler. When export is enabled without that host, startup reports a clear error; the agent command reports the diagnostic failure and continues. Exporter shutdown retires only its service scope, leaving the CLI scheduler available to other work. ## Gateway and node namespaces ### Session resource methods A plugin can declare `sessionAccess` when registering an additive Gateway method: ```typescript api.registerGatewayMethod("my-plugin.session.open", handleOpen, { scope: "operator.write", sessionAccess: { mode: "write", allowOwnSessionScope: true, requiredTool: "my_tool" }, }); ``` This requires a current authenticated profile, an existing canonical top-level `sessionKey`, and, when supplied, its matching `agentId`. Broad writers retain the session's sharing rules. `allowOwnSessionScope` additionally admits `operator.sessions.write` only for the caller's own session. `requiredTool` checks the canonical effective session tool policy and an admitted agent run's tool limits. Agent callers are bound to their own conversation. Currently, resource tool-policy admission does not support locked model selection. The handler receives `sessionAccessAuthority`. Call `assertCurrent()` before and after awaited preparation and immediately before effects. The router closes this invocation handle when the handler finishes; it cannot be reused to adopt new resources afterward. Use `retain()` during the handler to obtain an original-person access borrow with `signal`, `assertCurrent()` and `release()`, for example for an interactive viewer. Use `retainSession()` for a resource shared by independently authorized collaborators. That second borrow checks only the exact session incarnation and store generation; it does not authorize operations. Each operation still needs its own person/run admission. Normal row progress preserves both lifetimes; reset, deletion or physical-store replacement invalidates the session borrow. Release every borrow on failed startup, replacement and service cleanup. `sandboxRequired` describes the admitted session/role constraint. A consumer must provide a compliant backend or report that its backend is unsupported. This metadata does not turn a Gateway-hosted process into a sandbox. For tool presentation, `readGatewayToolOperatorScopes()` from `openclaw/plugin-sdk/agent-harness-runtime` returns a copy of the current admitted operator's scopes after checking that authority. It returns `undefined` for system/local calls without an operator capture. It does not grant permissions; the selected Gateway method still authorizes the request. ### Person access lifetimes `api.registerGatewayAccessPolicy({ authorize })` adds a plugin-owned access requirement to authenticated person admission. The callback receives the current configuration and the canonical profile's ID, email aliases, optional verified `githubAccountIds`, and assigned role. Account IDs come from the existing identity owner; display logins and public email do not establish that binding. The Gateway resolves `requiredByRole` from the person's effective role and this plugin's ID; role-bound policies use that fact instead of inferring a binding from the default role's name. Return `undefined` when the policy does not govern that person. Otherwise return `{ assertCurrent, signal }`; reject admission when the required access is absent. A named Gateway role can set `accessPolicyPlugin` to your plugin ID. That role requires a current authority from your registered policy, including when the plugin cannot load or its manifest is unavailable. Returning `undefined` does not satisfy an explicit role binding. Roles without the binding retain their existing policy behavior, and the Gateway owner remains independent. The assertion must check the original access source immediately before an action. Abort its signal when that source expires or is revoked, including plugin service shutdown. An ended source must stay ended if a later grant is created. A renewal may extend an uninterrupted source. Keep the source in its existing lifecycle owner and initialize it before accepting person access. Return a native `AbortSignal`. Registration preserves native cancellation and cleanup while keeping the assertion and callable abort-reason values bound to the plugin instance. Plugin retirement also ends captured access. The Gateway binds the returned authority to the original person and carries it through WebSocket and HTTP requests, and through commands admitted for a linked channel sender. Linked administrators must satisfy the same role-bound person policy, including after awaited command preparation. Revoking an admitted grant ends that command's authority; a replacement grant applies only to new admission. Explicitly configured command owners retain their independent authority. Ordinary transport disconnect is distinct from revocation. A policy must preserve independent staff access; it must not infer the requesting person's authority from a session's creator, display name, or sandbox state. Shared-secret system authority remains outside person policies. ### Durable person access grants A policy that supports deferred shared publication returns a stable UUID as `grantId` on its access authority and implements `resume({ config, profile, requiredByRole, grantId })`. The Gateway records the plugin ID and this original grant reference with the accepted requester and scope ceiling; it does not persist the authority callback, signal, credentials, or email aliases. The Gateway also retains opaque lifetime IDs for the person's original email bindings. Moving an original alias to another profile ends that publication authority, even if the alias is later restored. Display edits and changes to aliases added after admission preserve the original binding. The plugin's grant UUID remains independently checked; these identity facts cannot replace it. `resume` must check that exact original grant, even when the person's current role would otherwise be exempt. Return its current authority while it remains active, and `undefined` only when the grant is definitively ended, absent, or replaced. Throw while the service is starting or its state is unavailable, so recovery retains the pending request instead of treating an unreadable grant as revoked. A renewal can retain the UUID only if it commits before the old grant expires; reinvitation after expiry or revocation must use a new UUID. Policies without durable grant support still govern live admission. Their unclassified authority cannot be converted into a restartable shared publication request. Shared publication currently supports one original governing grant; multiple dependencies cannot be inferred from that single reference. A newly applicable policy also requires fresh publication admission.
api.runtime.gateway Call another Gateway method in process while preserving the current plugin's trusted runtime identity. This is intended for bundled or trusted official plugins that compose plugin-owned Gateway capabilities without opening a loopback WebSocket connection. ```typescript if (await api.runtime.gateway.isAvailable()) { const result = await api.runtime.gateway.request<{ callId: string }>( "voicecall.start", { to: "+15550001234", mode: "conversation" }, { timeoutMs: 60_000 }, ); } ``` Requests use `operator.write` scope and do not grant admin scope. Calls from arbitrary external plugins are rejected. Failed methods throw a `GatewayClientRequestError`, preserving structured `details`, retry metadata, and the Gateway error code for recovery flows. Use `isAvailable()` before choosing this path from tools that can also run in standalone agent processes. `await api.runtime.gateway.openPluginPanel({ panelId, sessionKey, agentId })` opens this plugin's registered native session panel in the requesting Control UI. Unlike arbitrary `request`, this narrow capability is also available to user-installed plugins. The host binds the plugin ID, keeps the caller's existing `operator.write` authority, and targets only the browser that requested the current action or agent turn. It rejects after plugin retirement, caller revocation, or requester disconnection; a session key never selects someone else's browser. `{ ok: true }` confirms command delivery, not completion of a plugin's asynchronous document load. Native UI must be enabled and the plugin must register the named panel. `await api.runtime.gateway.readSessionFacts({ sessionKeys })` reads at most 40 sessions and returns typed `{ sessions, warnings? }` data. Each session includes its key, identity, agent, bounded redacted title and message preview, run state (`active`, `idle`, or `failed`), optional observer digest (health, headline, assessment, revision), pull-request numbers and states, archive state, and last activity time. The message preview is capped at 400 characters. `pullRequestsUnavailable` distinguishes unknown PR state from a confirmed empty list. This lifecycle-bound read reuses the Gateway's session projection and context-bound PR snapshot owner, preserves current caller authority and session visibility, and omits incognito sessions. It returns prepared facts without waiting for Git or transcript enrichment; previews can be absent while enrichment is pending. Missing PR snapshots refresh in the background. Use `api.runtime.gateway.subscribeSessionChanges` to reread the affected `sessionKey` when facts change, and call the returned unsubscribe function when finished. Category-only changes carry `factsInvalidated: "category"`; projections that do not use session categories can ignore them. Unchanged facts need no age-based retry. Retained handles reject after their owner closes; no new SDK barrel export is needed. `api.runtime.gateway.withSessionFacts(select, async (snapshot) => result)` selects immutable facts through the same session-list filtering owner, without pagination. Selection supports agent, archive, automation, activity, and person filters, including the people facet. Unchanged session facts retain object identity across reads; `revision` changes with the selected content or its activity or retry deadline. Eligible human readers receive a stable opaque `scope` for their query and current viewer, profile, access, configuration, and redaction facts. Other callers receive `undefined`. The scope is not authority: the host rechecks the caller after the callback settles, including awaited plugin work. Consume reused results only inside this callback. Selected rows include `isMain`. Failed acquisition batches retain authorized roster fields with an `unavailable` reason; plugins can show their previous facts for the same session identity and `redactionRevision`. When that revision changes, discard retained text prepared under the old policy. Missing or no-longer-visible sessions are omitted; `missingSessionKeys` identifies selected roster entries whose current facts were omitted, so consumers can retire their fallback facts. Selected PR facts retry from 60 seconds up to 15 minutes, retain a last-confirmed list with `pullRequestsStale: true`, and reset on lifecycle replacement or a successful read. When redaction rules change, the host omits retained PR titles until fresh source text is available, while preserving confirmed states and retry deadlines. `activityExpiresAt` and `retryAt` describe the next relevant deadlines; no polling timer is created. Remove these selection-only fields when adapting facts to another public response contract. `await api.runtime.gateway.resolveGitHubAccount({ login, signal? })` resolves a public GitHub login to `{ accountId, login }` using the Gateway's configured GitHub API credential, with no anonymous retry. Bundled and trusted official plugins use the existing `users.list` / `operator.read` permission; the caller, plugin, and Gateway must stay active. Lookup failures return `{ error }` with the existing GitHub `statusCode` (404 not found, 429 rate limited, 502 upstream or network failure), a safe `message`, optional absolute `retryAtMs`, and `credentialConfigured`. Cancellation and authority failures reject. The optional capability is absent on older hosts; require an update rather than implementing a private lookup. The transport owns timeout and identity validation. `await api.runtime.gateway.withUserProfileIdentity({ profileId, emails, githubAccountIds }, run)` prepares the canonical profile's original binding lifetimes for up to 500 selected email aliases under the existing `users.list` / `operator.read` permission. Optional `githubAccountIds` binds up to 500 positive safe numeric account IDs to that same canonical profile. The callback receives a synchronous `assertCurrent()` function. Compose it with the action's own authorization in the store's final commit guard and immediately before dispatching an external mutation. It reads current facts published by the profile owner without querying SQLite on the calling thread. Moving an alias away and back, merging the selected profile, an unsettled profile mutation, or closing the caller invalidates the check. Selected account IDs must remain verified members of that profile. Unselected email bindings can change independently. The preparation is released when the callback settles, and retained assertions then reject. This capability checks the selected identity; it does not grant permission to perform the action or roll back a mutation already accepted externally.
api.runtime.nodes List connected nodes and invoke a node-host command from Gateway-loaded plugin code or from plugin CLI commands. Use this when a plugin owns local work on a paired device, for example a browser or audio bridge on another Mac. ```typescript const controller = new AbortController(); const { nodes } = await api.runtime.nodes.list({ connected: true }); const result = await api.runtime.nodes.invoke({ nodeId: "mac-studio", command: "my-plugin.command", params: { action: "start" }, timeoutMs: 30000, signal: controller.signal, }); ``` Pass the agent tool or request `AbortSignal` as `signal` when the caller can be canceled. Gateway-loaded calls forward cancellation to the paired node; node-host command handlers receive it as `context.signal` so they can stop in-flight requests and release local resources. Existing calls that omit the signal retain their previous behavior. Gateway-loaded plugins can open a connection-scoped binary channel to a registered node-host command with `nodes.openDuplex(...)`: ```typescript const controller = new AbortController(); const channel = await api.runtime.nodes.openDuplex({ nodeId: "paired-node", command: "my-plugin.image-bridge", params: { format: "png" }, timeoutMs: 30000, maxMessageBytes: 4 * 1024 * 1024, signal: controller.signal, }); const unsubscribe = channel.onMessage((message: Uint8Array) => { console.log("Received one complete binary message:", message.byteLength); }); try { await channel.send(Uint8Array.of(1, 2, 3)); const result = await channel.closed; } finally { unsubscribe(); channel.close(); } ``` `openDuplex` accepts the same node, command, parameters, timeout, idempotency key, session key, caller signal, and requested scopes as `nodes.invoke`, plus optional `maxMessageBytes` and `maxOutstandingDeliveryBytes` limits. The per-message limit defaults to 100 MiB and can be reduced, but never increased beyond 100 MiB. `maxOutstandingDeliveryBytes` bounds the combined size of complete messages whose asynchronous listener callbacks have not settled; it defaults to `maxMessageBytes`, cannot be smaller than that limit, and cannot exceed 100 MiB. A protocol that can follow a maximum-sized response with a bounded asynchronous notification may request a larger outstanding-delivery budget without raising its per-message ceiling. OpenClaw splits each binary message into ordered 8 KiB payload fragments that fit the existing 16 KiB transport-frame limit; callers always send and receive complete `Uint8Array` messages. Concurrent sends preserve message boundaries. Register the channel's single message listener immediately after `openDuplex` resolves. Before a listener is registered, OpenClaw buffers at most eight complete messages and 1 MiB total; exceeding either limit closes the invocation. The unsubscribe callback removes that listener. Listeners may return `Promise`; a thrown error or rejected promise, caller abort, `close()`, node disconnect, pairing change, plugin reload or retirement, or Gateway shutdown closes the channel and cancels outstanding node work. Successful node command completion and `channel.closed` wait for asynchronous message listeners already in progress. `close()` is idempotent, and retained channel methods reject after closure. `channel.closed` resolves with the successful command result or rejects with the node, authorization, transport, or cancellation error. Channels cannot reconnect or survive a node disconnection. The node plugin declares `duplex: true` and registers a message listener through the optional framed command I/O capability. Use `duplex: "optional"` when the same command also supports unary calls; it remains advertised on nodes without duplex support. Select binary behavior from an explicit request parameter, not from I/O presence alone: ```typescript api.registerNodeHostCommand({ command: "my-plugin.image-bridge", duplex: true, async handle(_paramsJSON, io) { if (!io?.frames) { throw new Error("Framed node command I/O is unavailable."); } const frames = io.frames; return await new Promise((resolve, reject) => { frames.onMessage((message) => { void frames.send(message).then(() => resolve('{"ok":true}'), reject); }); io.signal.addEventListener( "abort", () => reject(new Error("Node command was canceled.")), { once: true }, ); }); }, }); ``` Register `frames.onMessage(...)` before sending: the node announces framed readiness only after the listener exists, and `openDuplex` resolves only after both command dispatch and framed readiness. This prevents input from arriving before the plugin can consume it. The existing raw `emitChunk` and `onInput` helpers remain available to terminal-style commands. Interactive commands using `runNodePtyCommand` from `openclaw/plugin-sdk/node-host` can pass an `assertCurrent` callback for prepared source authority. The PTY owner rechecks it and the invocation's abort signal after asynchronous native loading, immediately before spawning. `openDuplex` is available only to a current, trusted in-process Gateway plugin runtime. Plugin CLI runtimes reject it with an actionable error; there is no remote polling or local fallback. Every invocation uses the same pairing, declared-command allowlist, plugin policy, approval, authorization, and connection-ownership checks as `nodes.invoke`. `nodes.list(...)` includes each connected node's advertised `nodePluginTools` descriptors when that node exposes plugin or MCP-backed tools to the agent. Those descriptors are live connection state: the Gateway drops them when the node disconnects, and a node can replace them with `node.pluginTools.update` after local plugin/MCP inventory changes. Inside the Gateway this runtime is in-process. In plugin CLI commands it calls the configured Gateway over RPC, so commands such as `openclaw googlemeet recover-tab` can inspect paired nodes from the terminal. Node commands still go through normal Gateway node pairing, command allowlists, plugin node-invoke policies, and node-local command handling. When execution identity auditing is enabled for an admitted run, those Gateway gates appear as enforced decision receipts. A successful node result is attribution-only. A policy that returns without calling its supplied `invokeNode` callback leaves the action unknown; returning a successful plugin result does not prove that the node action occurred. Plugins that expose node-hosted agent tools can set `agentTool.defaultPlatforms` for non-dangerous commands that should be allowlisted by default. Omit it when operators must opt in with `gateway.nodes.commands.allow`. Dangerous node-host commands should register a node-invoke policy with `api.registerNodeInvokePolicy(...)`; the policy runs in the Gateway after command allowlist checks and before the command is forwarded to the node, so direct `node.invoke` calls, node-hosted plugin tools, and higher-level plugin tools share the same enforcement path. A node-invoke policy receives the selected node's advertised `commands` and optional `caps`. Use those facts to require supported command behavior, then dispatch through the supplied `invokeNode` callback, which revalidates the current connection and pairing before forwarding the command. `allow-always` remains one policy decision unless the node-invoke policy explicitly declares `standingApproval: { kind: "placement", scope: "" }`. That opt-in permits later launches only for a high-risk command on the same current managed placement, node pairing, environment owner, workspace, and semantic capability scope, for at most 30 days and never across Gateway restart. Use a stable, content-free scope for a capability whose approval deliberately covers later argument changes. Do not opt in when the approved target or other request arguments must remain exact. A node command may declare `prepare(context)` for asynchronous native startup. Node-host initialization awaits it before publishing the initial manifest or connecting to the Gateway; plugin registration itself stays synchronous. Shared preparation callbacks run once per node registry initialization, not per invocation or reconnect. Optional providers should retain a known unavailable state on expected preparation failure and let `isAvailable` withhold their commands; throwing aborts node startup. Use `watchAvailability` for later availability changes and `onDisconnect` for execution cleanup. The cleanup callback returned by `watchAvailability` may return a promise. Node shutdown awaits that callback and reports cleanup failures.
The optional `scopes` field requests Gateway operator scopes for the invocation. OpenClaw honors it only for bundled plugins and trusted official plugin installations; requests from other plugins do not elevate the call. When `openDuplex` runs inside an authenticated Gateway request, its effective scopes never exceed that authenticated caller's actual scopes, even if a trusted plugin requests stronger scopes. Without an authenticated incoming client, existing trusted-plugin scope behavior applies. Use requested scopes only when a trusted plugin must invoke a node command with a stricter Gateway scope, such as `operator.admin`.
## Gateway service events Gateway-hosted services can use `ctx.invokeNode?.()` for their own registered node commands. This uses the service's identity, so a read-only document request can fetch a remote file without granting its caller `operator.write`. Authorize the public operation before using this capability. Node pairing, command grants, and plugin path policies still apply. The capability accepts no caller-selected scopes and stops accepting work when the service stops or its Gateway closes. Ordinary `api.runtime.nodes.invoke` keeps its caller's authority. `ctx.openNodeDuplex?.()` opens the same framed binary transport for the service's own commands registered with `duplex: true` or `duplex: "optional"`. It uses the same node policy and service lifetime as `invokeNode`; callers cannot select an identity or scopes. An optional `assertCurrent` callback adds the current operation's liveness check before dispatch and each frame. Closing the service cancels open channels. Gateway-hosted services also receive `ctx.getCron?.()` for the scheduler operations already available to Gateway hooks: `list`, `add`, `update`, `remove`, and `removeStaleJobFamily`. Non-Gateway service hosts omit this getter. Current service handles also expose `enqueueRun(id, mode)` for service-owned work. It uses the normal cron admission queue with the service's live authority, independently of a completed agent tool caller. Use `"if-enabled"` to request an immediate run without overriding a disabled job. Retained handles still reject when the service stops or the scheduler is replaced, including while waiting for admission. This optional method is absent on older hosts; it has no caller-scoped fallback. Current Gateway service handles also provide `await cron.isEnabled()` to observe whether automatic scheduling is enabled, including the `OPENCLAW_SKIP_CRON` override. It returns only a boolean, not storage metadata or permission to mutate jobs. The method is optional in the public type for older host implementations; its absence means unknown, not enabled or disabled. Consumers that support older hosts can keep their previous reconciliation behavior when it is absent. Disabled scheduling does not disable job CRUD or required plugin cleanup. Service cleanup retains the owning plugin's cleanup context so `stop()` can release resources after ordinary call admission closes. Keep the resources and unsubscribe functions acquired by that startup attempt, and release those exact handles. Cleanup failures do not imply that native resources were terminated; see [Plugin lifecycle and cleanup](https://funcoding.ai/agents/openclaw/plugins/sdk-runtime/#plugin-lifecycle-and-cleanup). Use the service's `start()` and `stop()` methods to own recurring reconciliation. They run for service or plugin replacement as well as Gateway startup and shutdown; full plugin replacement also runs `gateway_stop` and `gateway_start` for affected plugins. A service-only config reload does not replay those hooks. Each returned scheduler handle belongs to one service lifetime and one scheduler instance. Calls, including queued writes, reject once service shutdown begins or that scheduler is replaced. Call `ctx.getCron()` again to obtain the replacement scheduler while the service remains active. A service can declare `reload: { configPrefixes: ["myConfig.service"] }` alongside its `id`, `start`, and `stop`. After a matching config change commits, the Gateway stops that service and calls `start(ctx)` again with the new `ctx.config`. Only loaded services declaring the matching prefix are replaced; overlapping owners all refresh. Existing equal or narrower restart or no-op policies still take precedence. Each start receives a new capability lease and health reporter. Stop must release resources before resolving; failed replacement cleanup or startup triggers Gateway recovery. A full plugin replacement subsumes these service restarts. The stop hook runs after that attempt's original start settles. A replacement deadline can end the caller's wait and revoke service capabilities while final cleanup remains owned. Trusted official diagnostics exporter services can also receive `ctx.internalDiagnostics.getRuntimeIdentity?.()`. It returns the hosting process's canonical `processInstanceId` and optional loaded `buildId`, with no filesystem lookup or RPC. Capture it during service startup; a retained getter throws after the service lease is revoked. Hosts that do not provide this optional capability leave runtime identity unavailable. This diagnostic fact does not grant authority or identify a service-reload epoch. Their `ctx.internalDiagnostics.onEvent(listener, filter?, options?)` subscription delivers events, trust metadata, and a frozen private-data object. Exporters that only need events and metadata can pass `{ includePrivateData: false }` as the third registration argument to skip private payload copies and receive a frozen empty object instead. This preserves event filters, trusted-only delivery, and service lease cleanup. Private data remains enabled by default; older hosts ignore the optional argument and retain their existing copying behavior. Long-lived services registered with `api.registerService(...)` receive a process-local `ctx.gatewayEvents` facade when the process runs a Gateway broadcaster; in runtimes without one the field is absent, so feature-detect it and keep a fallback (for example a coarse poll). Use `onSessionsChanged(...)` to react after the Gateway broadcasts a `sessions.changed` notice: ```typescript let unsubscribeSessionsChanged: (() => void) | undefined; api.registerService({ id: "session-index", start(ctx) { unsubscribeSessionsChanged = ctx.gatewayEvents?.onSessionsChanged((event) => { // event: { sessionKey, agentId?, label?, displayName?, reason?, phase? } // refreshSession is your plugin's own handler, not an SDK export. refreshSession(event.sessionKey); }); }, stop() { unsubscribeSessionsChanged?.(); unsubscribeSessionsChanged = undefined; }, }); ``` The handler runs in the Gateway process and does not add a Gateway protocol subscription. Keep the returned unsubscribe function and call it during service cleanup. The payload is a lightweight change notice; use `api.runtime.agent.session.getSessionEntry(...)` when the plugin needs the full current session entry. OpenClaw calls a service's `stop()` at most once per startup attempt, including when a replacement times out before startup fails. Failed-start rollback and shutdown share the same cleanup result; a cleanup failure is recorded rather than retried within that attempt. If a replacement fails, the Gateway may call `start()` again on the previous service to restore it. Recreate resources released by `stop()` and reset per-start flags so tools and background work remain usable after rollback. Service startup failures from a returned or awaited promise are recorded automatically. A service that intentionally starts required work in the background must report later failure and recovery through its generation-bound health reporter: ```typescript // startIndexWorker and stopIndexWorker are your plugin's own background-work // helpers, not SDK exports. api.registerService({ id: "index-worker", start(ctx) { void startIndexWorker().then( () => ctx.serviceHealth?.clearFailure(), (error) => ctx.serviceHealth?.reportFailure(error), ); }, stop() { stopIndexWorker(); }, }); ``` The reporter is revoked when the service stops or its plugin registry generation is replaced, so a late callback from an old generation cannot overwrite current health. Prefer returning the startup promise when the service is not usable until that promise settles; use the reporter only for deliberately nonblocking work that owns its own stop path.