docs(plugins): document runtime config APIs

docs/plugins/sdk-runtime.md

@@ -25,6 +25,26 @@ register(api) {
 }
 ```
 
+## Config Loading And Writes
+
+Prefer config that was already passed into the active call path, for example `api.config` during registration or a `cfg` argument on channel/provider callbacks. This keeps one process snapshot flowing through the work instead of reparsing config on hot paths.
+
+Use `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 `ctx.runtimeConfig` plus `ctx.getRuntimeConfig()`. Use the getter inside a long-lived tool's `execute` callback when config can change after the tool definition was created.
+
+Persist changes with `api.runtime.config.mutateConfigFile(...)` or `api.runtime.config.replaceConfigFile(...)`. Each write must choose an explicit `afterWrite` policy:
+
+- `afterWrite: { mode: "auto" }` lets the gateway reload planner decide.
+- `afterWrite: { mode: "restart", reason: "..." }` forces a clean restart when the writer knows hot reload is unsafe.
+- `afterWrite: { mode: "none", reason: "..." }` suppresses automatic reload/restart only when the caller owns the follow-up.
+
+The mutation helpers return `afterWrite` plus a typed `followUp` summary so callers can log or test whether they requested a restart. The gateway still owns when that restart actually happens.
+
+`api.runtime.config.loadConfig()` and `api.runtime.config.writeConfigFile(...)` are deprecated compatibility helpers. Bundled plugins must not use them; the architecture guard fails if production plugin code calls them or imports those helpers from plugin SDK subpaths.
+
+Internal OpenClaw runtime code has the same direction: load config once at the CLI, gateway, or process boundary, then pass that value through. 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
 
 <AccordionGroup>
@@ -284,13 +304,25 @@ register(api) {
 
   </Accordion>
   <Accordion title="api.runtime.config">
-    Config load and write.
+    Current runtime config snapshot and transactional config writes. Prefer
+    config that was already passed into the active call path; use
+    `current()` only when the handler needs the process snapshot directly.
 
     ```typescript
-    const cfg = await api.runtime.config.loadConfig();
-    await api.runtime.config.writeConfigFile(cfg);
+    const cfg = api.runtime.config.current();
+    await api.runtime.config.mutateConfigFile({
+      afterWrite: { mode: "auto" },
+      mutate(draft) {
+        draft.plugins ??= {};
+      },
+    });
     ```
 
+    `mutateConfigFile(...)` and `replaceConfigFile(...)` return a `followUp`
+    value, for example `{ mode: "restart", requiresRestart: true, reason }`,
+    which records the writer intent without taking restart control away from the
+    gateway.
+
   </Accordion>
   <Accordion title="api.runtime.system">
     System-level utilities.