From c055a72c3d69504b8bc50ff0dfdf615977a2b79e Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Mon, 27 Apr 2026 14:01:12 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@4336a7f3a9c6f44fa2d9310fc2eabd1ba3b21c5f --- .openclaw-sync/source.json | 4 ++-- docs/plugins/sdk-migration.md | 19 +++++++++++++++++++ docs/plugins/sdk-runtime.md | 6 ++++++ docs/plugins/sdk-subpaths.md | 12 +++++++++--- 4 files changed, 36 insertions(+), 5 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index b370c5b51..62acc50ff 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "1f7b7c249ad3c128384eebb17fc40e19d177b0df", - "syncedAt": "2026-04-27T13:55:16.350Z" + "sha": "4336a7f3a9c6f44fa2d9310fc2eabd1ba3b21c5f", + "syncedAt": "2026-04-27T13:59:46.345Z" } diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 49cb03008..4d735f752 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -129,6 +129,25 @@ releases. must receive config from their boundary, and long-lived runtime modules have zero allowed ambient `loadConfig()` calls. + New plugin code should also avoid importing the broad + `openclaw/plugin-sdk/config-runtime` compatibility barrel. Use the narrow + SDK subpath that matches the job: + + | Need | Import | + | --- | --- | + | Config types such as `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | + | Already-loaded config assertions and plugin-entry config lookup | `openclaw/plugin-sdk/plugin-config-runtime` | + | Current runtime snapshot reads | `openclaw/plugin-sdk/runtime-config-snapshot` | + | Config writes | `openclaw/plugin-sdk/config-mutation` | + | Session store helpers | `openclaw/plugin-sdk/session-store-runtime` | + | Markdown table config | `openclaw/plugin-sdk/markdown-table-runtime` | + | Group policy runtime helpers | `openclaw/plugin-sdk/runtime-group-policy` | + | Secret input resolution | `openclaw/plugin-sdk/secret-input-runtime` | + | Model/session overrides | `openclaw/plugin-sdk/model-session-runtime` | + + Bundled production plugins are scanner-guarded against the broad barrel so + imports stay local to the behavior they need. + diff --git a/docs/plugins/sdk-runtime.md b/docs/plugins/sdk-runtime.md index 2412111c7..3414d3a63 100644 --- a/docs/plugins/sdk-runtime.md +++ b/docs/plugins/sdk-runtime.md @@ -43,6 +43,12 @@ The mutation helpers return `afterWrite` plus a typed `followUp` summary so call `api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated compatibility helpers under `runtime-config-load-write`. They warn once at runtime, and bundled plugins must not use them; the config boundary guards fail if production 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 +`openclaw/plugin-sdk/config-runtime` compatibility barrel: `config-types` for +types, `plugin-config-runtime` for already-loaded config assertions and plugin +entry lookup, `runtime-config-snapshot` for current process snapshots, and +`config-mutation` for writes. + 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 `loadConfig()` calls; use a passed `cfg`, a request `context.getRuntimeConfig()`, or `getRuntimeConfig()` at an explicit process boundary. ## Runtime namespaces diff --git a/docs/plugins/sdk-subpaths.md b/docs/plugins/sdk-subpaths.md index e3adf2818..9fc0f2da9 100644 --- a/docs/plugins/sdk-subpaths.md +++ b/docs/plugins/sdk-subpaths.md @@ -161,7 +161,10 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/process-runtime` | Process exec helpers | | `plugin-sdk/cli-runtime` | CLI formatting, wait, version, argument-invocation, and lazy command-group helpers | | `plugin-sdk/gateway-runtime` | Gateway client, gateway CLI RPC, gateway protocol errors, and channel-status patch helpers | - | `plugin-sdk/config-runtime` | Config load/write helpers and plugin-config lookup helpers | + | `plugin-sdk/config-types` | Type-only config surface for plugin config shapes such as `OpenClawConfig` and channel/provider config types | + | `plugin-sdk/plugin-config-runtime` | Runtime plugin-config lookup helpers such as `requireRuntimeConfig`, `resolvePluginConfigObject`, and `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Transactional config mutation helpers such as `mutateConfigFile`, `replaceConfigFile`, and `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Current process config snapshot helpers such as `getRuntimeConfig`, `getRuntimeConfigSnapshot`, and test snapshot setters | | `plugin-sdk/telegram-command-config` | Telegram command-name/description normalization and duplicate/conflict checks, even when the bundled Telegram contract surface is unavailable | | `plugin-sdk/text-autolink-runtime` | File-reference autolink detection without the broad text-runtime barrel | | `plugin-sdk/approval-runtime` | Exec/plugin approval helpers, approval-capability builders, auth/profile helpers, native routing/runtime helpers, and structured approval display path formatting | @@ -170,7 +173,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/reply-history` | Shared short-window reply-history helpers such as `buildHistoryContext`, `recordPendingHistoryEntry`, and `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Narrow text/markdown chunking helpers | - | `plugin-sdk/session-store-runtime` | Session store path + updated-at helpers | + | `plugin-sdk/session-store-runtime` | Session store path, session-key, updated-at, and store mutation helpers | + | `plugin-sdk/cron-store-runtime` | Cron store path/load/save helpers | | `plugin-sdk/state-paths` | State/OAuth dir path helpers | | `plugin-sdk/routing` | Route/session-key/account binding helpers such as `resolveAgentRoute`, `buildAgentSessionKey`, and `resolveDefaultAgentBoundAccountId` | | `plugin-sdk/status-helpers` | Shared channel/account status summary helpers, runtime-state defaults, and issue metadata helpers | @@ -184,6 +188,8 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/temp-path` | Shared temp-download path helpers | | `plugin-sdk/logging-core` | Subsystem logger and redaction helpers | | `plugin-sdk/markdown-table-runtime` | Markdown table mode and conversion helpers | + | `plugin-sdk/model-session-runtime` | Model/session override helpers such as `applyModelOverrideToSessionEntry` and `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Talk provider config resolution helpers | | `plugin-sdk/json-store` | Small JSON state read/write helpers | | `plugin-sdk/file-lock` | Re-entrant file-lock helpers | | `plugin-sdk/persistent-dedupe` | Disk-backed dedupe cache helpers | @@ -207,7 +213,7 @@ For the plugin authoring guide, see [Plugin SDK overview](/plugins/sdk-overview) | `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch without proxy/guarded-fetch imports | | `plugin-sdk/response-limit-runtime` | Bounded response-body reader without the broad media runtime surface | | `plugin-sdk/session-binding-runtime` | Current conversation binding state without configured binding routing or pairing stores | - | `plugin-sdk/session-store-runtime` | Session-store read helpers without broad config writes/maintenance imports | + | `plugin-sdk/session-store-runtime` | Session-store helpers without broad config writes/maintenance imports | | `plugin-sdk/context-visibility-runtime` | Context visibility resolution and supplemental context filtering without broad config/security imports | | `plugin-sdk/string-coerce-runtime` | Narrow primitive record/string coercion and normalization helpers without markdown/logging imports | | `plugin-sdk/host-runtime` | Hostname and SCP host normalization helpers |