From aa5d60f371dbf507748acfeb1f845e10cbf5b034 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Fri, 24 Apr 2026 20:26:32 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@7bd74758c5f54c546b52708359a25c08cae74ad7 --- .openclaw-sync/source.json | 4 +- .../.generated/plugin-sdk-api-baseline.sha256 | 4 +- docs/plugins/building-plugins.md | 11 +++--- docs/plugins/manifest.md | 38 ++++++++++--------- docs/plugins/sdk-agent-harness.md | 8 ++-- docs/plugins/sdk-migration.md | 9 +++-- docs/plugins/sdk-overview.md | 15 ++++---- 7 files changed, 48 insertions(+), 41 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index f0365a10f..f9045b627 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "272313877dc867f83008810302b3b6eba4bb1900", - "syncedAt": "2026-04-24T20:24:42.755Z" + "sha": "7bd74758c5f54c546b52708359a25c08cae74ad7", + "syncedAt": "2026-04-24T20:25:04.210Z" } diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256 index 66a2a0979..8487f07db 100644 --- a/docs/.generated/plugin-sdk-api-baseline.sha256 +++ b/docs/.generated/plugin-sdk-api-baseline.sha256 @@ -1,2 +1,2 @@ -b86e6785acbd0f8f0f012691ce823c2e8d52bfd2507c2258408503162abb9adf plugin-sdk-api-baseline.json -e10acbed6c7c1b21700e358411c73877bdc0cb59ce102bafe680e210a2ac741b plugin-sdk-api-baseline.jsonl +a2005473b59e26995f563e8bd3f1c6782bd3ee193a65dd3255160d40e505fa4d plugin-sdk-api-baseline.json +5778c0bb6cfc85c1b0665ec431269bcb43b8891720d0b30467681420ab411721 plugin-sdk-api-baseline.jsonl diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index c69890d28..5d5377cdf 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -170,11 +170,12 @@ A single plugin can register any number of capabilities via the `api` object: For the full registration API, see [SDK Overview](/plugins/sdk-overview#registration-api). -Use `api.registerAgentToolResultMiddleware(...)` when a plugin needs async -tool-result rewriting before the model sees the output. Declare the targeted -harnesses in `contracts.agentToolResultMiddleware`, for example -`["pi", "codex-app-server"]`. Prefer regular OpenClaw plugin hooks when the -work does not need pre-model tool-result timing. +Bundled plugins can use `api.registerAgentToolResultMiddleware(...)` when they +need async tool-result rewriting before the model sees the output. Declare the +targeted harnesses in `contracts.agentToolResultMiddleware`, for example +`["pi", "codex-app-server"]`. This is a trusted bundled-plugin seam; external +plugins should prefer regular OpenClaw plugin hooks unless OpenClaw grows an +explicit trust policy for this capability. If your plugin registers custom gateway RPC methods, keep them on a plugin-specific prefix. Core admin namespaces (`config.*`, diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index 4617b4393..cfca2d643 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -422,26 +422,28 @@ read without importing the plugin runtime. Each list is optional: -| Field | Type | What it means | -| -------------------------------- | ---------- | ---------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Deprecated embedded extension factory ids. | -| `agentToolResultMiddleware` | `string[]` | Harness ids this plugin may register tool-result middleware for. | -| `externalAuthProviders` | `string[]` | Provider ids whose external auth profile hook this plugin owns. | -| `speechProviders` | `string[]` | Speech provider ids this plugin owns. | -| `realtimeTranscriptionProviders` | `string[]` | Realtime-transcription provider ids this plugin owns. | -| `realtimeVoiceProviders` | `string[]` | Realtime-voice provider ids this plugin owns. | -| `memoryEmbeddingProviders` | `string[]` | Memory embedding provider ids this plugin owns. | -| `mediaUnderstandingProviders` | `string[]` | Media-understanding provider ids this plugin owns. | -| `imageGenerationProviders` | `string[]` | Image-generation provider ids this plugin owns. | -| `videoGenerationProviders` | `string[]` | Video-generation provider ids this plugin owns. | -| `webFetchProviders` | `string[]` | Web-fetch provider ids this plugin owns. | -| `webSearchProviders` | `string[]` | Web-search provider ids this plugin owns. | -| `tools` | `string[]` | Agent tool names this plugin owns for bundled contract checks. | +| Field | Type | What it means | +| -------------------------------- | ---------- | --------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Deprecated embedded extension factory ids. | +| `agentToolResultMiddleware` | `string[]` | Harness ids a bundled plugin may register tool-result middleware for. | +| `externalAuthProviders` | `string[]` | Provider ids whose external auth profile hook this plugin owns. | +| `speechProviders` | `string[]` | Speech provider ids this plugin owns. | +| `realtimeTranscriptionProviders` | `string[]` | Realtime-transcription provider ids this plugin owns. | +| `realtimeVoiceProviders` | `string[]` | Realtime-voice provider ids this plugin owns. | +| `memoryEmbeddingProviders` | `string[]` | Memory embedding provider ids this plugin owns. | +| `mediaUnderstandingProviders` | `string[]` | Media-understanding provider ids this plugin owns. | +| `imageGenerationProviders` | `string[]` | Image-generation provider ids this plugin owns. | +| `videoGenerationProviders` | `string[]` | Video-generation provider ids this plugin owns. | +| `webFetchProviders` | `string[]` | Web-fetch provider ids this plugin owns. | +| `webSearchProviders` | `string[]` | Web-search provider ids this plugin owns. | +| `tools` | `string[]` | Agent tool names this plugin owns for bundled contract checks. | `contracts.embeddedExtensionFactories` is retained for bundled compatibility -code that still needs direct Pi embedded-runner events. New tool-result -transforms should declare `contracts.agentToolResultMiddleware` and register -with `api.registerAgentToolResultMiddleware(...)` instead. +code that still needs direct Pi embedded-runner events. New bundled +tool-result transforms should declare `contracts.agentToolResultMiddleware` +and register with `api.registerAgentToolResultMiddleware(...)` instead. +External plugins cannot register tool-result middleware because the seam can +rewrite high-trust tool output before the model sees it. Provider plugins that implement `resolveExternalAuthProfiles` should declare `contracts.externalAuthProviders`. Plugins without the declaration still run diff --git a/docs/plugins/sdk-agent-harness.md b/docs/plugins/sdk-agent-harness.md index 60eeff4e8..e5bb2d49c 100644 --- a/docs/plugins/sdk-agent-harness.md +++ b/docs/plugins/sdk-agent-harness.md @@ -146,11 +146,11 @@ OpenClaw only runs against the protocol surface it has been tested with. ### Tool-result middleware -Plugins can attach harness-neutral tool-result middleware through +Bundled plugins can attach harness-neutral tool-result middleware through `api.registerAgentToolResultMiddleware(...)` when their manifest declares the -targeted harness ids in `contracts.agentToolResultMiddleware`. This is the seam -for async tool-result transforms that must run before PI or Codex feeds tool -output back into the model. +targeted harness ids in `contracts.agentToolResultMiddleware`. This trusted +seam is for async tool-result transforms that must run before PI or Codex feeds +tool output back into the model. Legacy bundled plugins can still use `api.registerCodexAppServerExtensionFactory(...)` for Codex app-server-only diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 97800589d..671e94b77 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -91,8 +91,9 @@ releases. - Replace Pi-only `api.registerEmbeddedExtensionFactory(...)` tool-result - handlers with harness-neutral middleware. + Bundled plugins should replace Pi-only + `api.registerEmbeddedExtensionFactory(...)` tool-result handlers with + harness-neutral middleware. ```typescript // Before: Pi-only compatibility hook @@ -121,7 +122,9 @@ releases. ``` Keep `contracts.embeddedExtensionFactories` only for bundled compatibility - code that still needs direct Pi embedded-runner events. + code that still needs direct Pi embedded-runner events. External plugins + cannot register tool-result middleware because it can rewrite high-trust + tool output before the model sees it. diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index a7421ef8f..9a31d935f 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -112,14 +112,15 @@ methods: - Use `api.registerAgentToolResultMiddleware(...)` when a plugin needs to - rewrite a tool result after execution and before the harness feeds that - result back into the model. This is the harness-neutral seam for async output - reducers such as tokenjuice. + Bundled plugins can use `api.registerAgentToolResultMiddleware(...)` when + they need to rewrite a tool result after execution and before the harness + feeds that result back into the model. This is the trusted harness-neutral + seam for async output reducers such as tokenjuice. -Plugins must declare `contracts.agentToolResultMiddleware` for each targeted -harness, for example `["pi", "codex-app-server"]`. Keep normal OpenClaw -plugin hooks for work that does not need pre-model tool-result timing. +Bundled plugins must declare `contracts.agentToolResultMiddleware` for each +targeted harness, for example `["pi", "codex-app-server"]`. External plugins +cannot register this middleware; keep normal OpenClaw plugin hooks for work +that does not need pre-model tool-result timing.