Matrix: restore startup and doctor migration

.github/labeler.yml

@@ -314,7 +314,3 @@
   - changed-files:
       - any-glob-to-any-file:
           - "extensions/xiaomi/**"
-"extensions: fal":
-  - changed-files:
-      - any-glob-to-any-file:
-          - "extensions/fal/**"

.github/workflows/ci.yml

@@ -304,194 +304,6 @@ jobs:
       - name: Enforce safe external URL opening policy
         run: pnpm lint:ui:no-raw-window-open
 
-  plugin-extension-boundary:
-    name: "plugin-extension-boundary"
-    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
-    runs-on: blacksmith-16vcpu-ubuntu-2404
-    env:
-      PLUGIN_EXTENSION_BOUNDARY_ENFORCE_AFTER: "2026-03-24T05:00:00Z"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          submodules: false
-
-      - name: Setup Node environment
-        uses: ./.github/actions/setup-node-env
-        with:
-          install-bun: "false"
-          use-sticky-disk: "false"
-
-      - name: Run plugin extension boundary guard with grace period
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          tmp_output="$(mktemp)"
-          if pnpm run lint:plugins:no-extension-imports >"$tmp_output" 2>&1; then
-            cat "$tmp_output"
-            rm -f "$tmp_output"
-            exit 0
-          fi
-
-          status=$?
-          cat "$tmp_output"
-          rm -f "$tmp_output"
-
-          now_epoch="$(date -u +%s)"
-          enforce_epoch="$(date -u -d "$PLUGIN_EXTENSION_BOUNDARY_ENFORCE_AFTER" +%s)"
-          fix_instructions="If you are an LLM agent fixing this: run 'pnpm run lint:plugins:no-extension-imports', remove src/plugins/** -> extensions/** imports where possible, and if the remaining inventory is intentional for now update test/fixtures/plugin-extension-import-boundary-inventory.json in the same PR."
-
-          if [ "$now_epoch" -lt "$enforce_epoch" ]; then
-            echo "::warning::Plugin extension import boundary violations are temporarily allowed until ${PLUGIN_EXTENSION_BOUNDARY_ENFORCE_AFTER}. This grace period ends in one week from the rollout date. After that timestamp this job will fail unless the inventory is reduced or the baseline is intentionally updated. ${fix_instructions}"
-            exit 0
-          fi
-
-          echo "::error::Plugin extension import boundary grace period ended at ${PLUGIN_EXTENSION_BOUNDARY_ENFORCE_AFTER}. ${fix_instructions}"
-          exit "$status"
-
-  web-search-provider-boundary:
-    name: "web-search-provider-boundary"
-    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
-    runs-on: blacksmith-16vcpu-ubuntu-2404
-    env:
-      WEB_SEARCH_PROVIDER_BOUNDARY_ENFORCE_AFTER: "2026-03-24T05:00:00Z"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          submodules: false
-
-      - name: Setup Node environment
-        uses: ./.github/actions/setup-node-env
-        with:
-          install-bun: "false"
-          use-sticky-disk: "false"
-
-      - name: Run web search provider boundary guard with grace period
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          tmp_output="$(mktemp)"
-          if pnpm run lint:web-search-provider-boundaries >"$tmp_output" 2>&1; then
-            cat "$tmp_output"
-            rm -f "$tmp_output"
-            exit 0
-          fi
-
-          status=$?
-          cat "$tmp_output"
-          rm -f "$tmp_output"
-
-          now_epoch="$(date -u +%s)"
-          enforce_epoch="$(date -u -d "$WEB_SEARCH_PROVIDER_BOUNDARY_ENFORCE_AFTER" +%s)"
-          fix_instructions="If you are an LLM agent fixing this: run 'pnpm run lint:web-search-provider-boundaries', move provider-specific web-search logic out of core, and if the remaining inventory is intentional for now update test/fixtures/web-search-provider-boundary-inventory.json in the same PR."
-
-          if [ "$now_epoch" -lt "$enforce_epoch" ]; then
-            echo "::warning::Web search provider boundary violations are temporarily allowed until ${WEB_SEARCH_PROVIDER_BOUNDARY_ENFORCE_AFTER}. This grace period ends in one week from the rollout date. After that timestamp this job will fail unless the inventory is reduced or the baseline is intentionally updated. ${fix_instructions}"
-            exit 0
-          fi
-
-          echo "::error::Web search provider boundary grace period ended at ${WEB_SEARCH_PROVIDER_BOUNDARY_ENFORCE_AFTER}. ${fix_instructions}"
-          exit "$status"
-
-  extension-src-outside-plugin-sdk-boundary:
-    name: "extension-src-outside-plugin-sdk-boundary"
-    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
-    runs-on: blacksmith-16vcpu-ubuntu-2404
-    env:
-      EXTENSION_PLUGIN_SDK_BOUNDARY_ENFORCE_AFTER: "2026-03-24T05:00:00Z"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          submodules: false
-
-      - name: Setup Node environment
-        uses: ./.github/actions/setup-node-env
-        with:
-          install-bun: "false"
-          use-sticky-disk: "false"
-
-      - name: Run extension src boundary guard with grace period
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          tmp_output="$(mktemp)"
-          if pnpm run lint:extensions:no-src-outside-plugin-sdk >"$tmp_output" 2>&1; then
-            cat "$tmp_output"
-            rm -f "$tmp_output"
-            exit 0
-          fi
-
-          status=$?
-          cat "$tmp_output"
-          rm -f "$tmp_output"
-
-          now_epoch="$(date -u +%s)"
-          enforce_epoch="$(date -u -d "$EXTENSION_PLUGIN_SDK_BOUNDARY_ENFORCE_AFTER" +%s)"
-          fix_instructions="If you are an LLM agent fixing this: run 'pnpm run lint:extensions:no-src-outside-plugin-sdk', move extension imports off core src paths and onto src/plugin-sdk/**, and if the remaining inventory is intentional for now update test/fixtures/extension-src-outside-plugin-sdk-inventory.json in the same PR."
-
-          if [ "$now_epoch" -lt "$enforce_epoch" ]; then
-            echo "::warning::Extension src boundary violations are temporarily allowed until ${EXTENSION_PLUGIN_SDK_BOUNDARY_ENFORCE_AFTER}. This grace period ends in one week from the rollout date. After that timestamp this job will fail unless the inventory is reduced or the baseline is intentionally updated. ${fix_instructions}"
-            exit 0
-          fi
-
-          echo "::error::Extension src boundary grace period ended at ${EXTENSION_PLUGIN_SDK_BOUNDARY_ENFORCE_AFTER}. ${fix_instructions}"
-          exit "$status"
-
-  extension-plugin-sdk-internal-boundary:
-    name: "extension-plugin-sdk-internal-boundary"
-    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
-    runs-on: blacksmith-16vcpu-ubuntu-2404
-    env:
-      EXTENSION_PLUGIN_SDK_INTERNAL_ENFORCE_AFTER: "2026-03-24T05:00:00Z"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          submodules: false
-
-      - name: Setup Node environment
-        uses: ./.github/actions/setup-node-env
-        with:
-          install-bun: "false"
-          use-sticky-disk: "false"
-
-      - name: Run extension plugin-sdk-internal guard with grace period
-        shell: bash
-        run: |
-          set -euo pipefail
-
-          tmp_output="$(mktemp)"
-          if pnpm run lint:extensions:no-plugin-sdk-internal >"$tmp_output" 2>&1; then
-            cat "$tmp_output"
-            rm -f "$tmp_output"
-            exit 0
-          fi
-
-          status=$?
-          cat "$tmp_output"
-          rm -f "$tmp_output"
-
-          now_epoch="$(date -u +%s)"
-          enforce_epoch="$(date -u -d "$EXTENSION_PLUGIN_SDK_INTERNAL_ENFORCE_AFTER" +%s)"
-          fix_instructions="If you are an LLM agent fixing this: run 'pnpm run lint:extensions:no-plugin-sdk-internal', remove extension imports of src/plugin-sdk-internal/** in favor of src/plugin-sdk/**, and if the remaining inventory is intentional for now update test/fixtures/extension-plugin-sdk-internal-inventory.json in the same PR."
-
-          if [ "$now_epoch" -lt "$enforce_epoch" ]; then
-            echo "::warning::Extension plugin-sdk-internal boundary violations are temporarily allowed until ${EXTENSION_PLUGIN_SDK_INTERNAL_ENFORCE_AFTER}. This grace period ends in one week from the rollout date. After that timestamp this job will fail unless the inventory is reduced or the baseline is intentionally updated. ${fix_instructions}"
-            exit 0
-          fi
-
-          echo "::error::Extension plugin-sdk-internal boundary grace period ended at ${EXTENSION_PLUGIN_SDK_INTERNAL_ENFORCE_AFTER}. ${fix_instructions}"
-          exit "$status"
-
   build-smoke:
     name: "build-smoke"
     needs: [docs-scope, changed-scope]

AGENTS.md

@@ -114,7 +114,6 @@
 - Never add `@ts-nocheck` and do not disable `no-explicit-any`; fix root causes and update Oxlint/Oxfmt config only when required.
 - Dynamic import guardrail: do not mix `await import("x")` and static `import ... from "x"` for the same module in production code paths. If you need lazy loading, create a dedicated `*.runtime.ts` boundary (that re-exports from `x`) and dynamically import that boundary from lazy callers only.
 - Dynamic import verification: after refactors that touch lazy-loading/module boundaries, run `pnpm build` and check for `[INEFFECTIVE_DYNAMIC_IMPORT]` warnings before submitting.
-- Extension SDK self-import guardrail: inside an extension package, do not import that same extension via `openclaw/plugin-sdk/<extension>` from production files. Route internal imports through a local barrel such as `./api.ts` or `./runtime-api.ts`, and keep the `plugin-sdk/<extension>` path as the external contract only.
 - Never share class behavior via prototype mutation (`applyPrototypeMixins`, `Object.defineProperty` on `.prototype`, or exporting `Class.prototype` for merges). Use explicit inheritance/composition (`A extends B extends C`) or helper composition so TypeScript can typecheck.
 - If this pattern is needed, stop and get explicit approval before shipping; default behavior is to split/refactor into an explicit class hierarchy and keep members strongly typed.
 - In tests, prefer per-instance stubs over prototype mutation (`SomeClass.prototype.method = ...`) unless a test explicitly documents why prototype-level patching is required.

CHANGELOG.md

@@ -39,7 +39,12 @@ Docs: https://docs.openclaw.ai
 - Plugins/Chutes: add a bundled Chutes provider with plugin-owned OAuth/API-key auth, dynamic model discovery, and default-on extension wiring. (#41416) Thanks @Veightor.
 - Plugins/binding: add `onConversationBindingResolved(...)` so plugins can react immediately after bind approvals or denies without blocking channel interaction acknowledgements. (#48678) Thanks @huntharo.
 - CLI/config: expand `config set` with SecretRef and provider builder modes, JSON/batch assignment support, and `--dry-run` validation with structured JSON output. (#49296) Thanks @joshavant.
-- Control UI/appearance: unify theme border radii across Claw, Knot, and Dash, and add a Roundness slider to the Appearance settings so users can adjust corner radius from sharp to fully rounded. Thanks @BunsDev.
+
+### Breaking
+
+- Browser/Chrome MCP: remove the legacy Chrome extension relay path, bundled extension assets, `driver: "extension"`, and `browser.relayBindHost`. Run `openclaw doctor --fix` to migrate host-local browser config to `existing-session` / `user`; Docker, headless, sandbox, and remote browser flows still use raw CDP. (#47893) Thanks @vincentkoc.
+- Plugins/runtime: remove the public `openclaw/extension-api` surface with no compatibility shim. Bundled plugins must use injected runtime for host-side operations (for example `api.runtime.agent.runEmbeddedPiAgent`) and any remaining direct imports must come from narrow `openclaw/plugin-sdk/*` subpaths instead of the monolithic SDK root.
+- Tools/image generation: standardize the stock image create/edit path on the core `image_generate` tool. The old `nano-banana-pro` docs/examples are gone; if you previously copied that sample-skill config, switch to `agents.defaults.imageGenerationModel` for built-in image generation or install a separate third-party skill explicitly.
 
 ### Fixes
 
@@ -123,6 +128,9 @@ Docs: https://docs.openclaw.ai
 - Telegram/network: preserve sticky IPv4 fallback state across polling restarts so hosts with unstable IPv6 to `api.telegram.org` stop re-triggering repeated Telegram timeouts after each restart. (#48282) Thanks @yassinebkr.
 - Plugins/subagents: forward per-run provider and model overrides through gateway plugin subagent dispatch so plugin-launched agent delegations honor explicit model selection again. (#48277) Thanks @jalehman.
 - Agents/compaction: write minimal boundary summaries for empty preparations while keeping split-turn prefixes on the normal path, so no-summarizable-message sessions stop retriggering the safeguard loop. (#42215) thanks @lml2468.
+
+### Fixes
+
 - Agents/bootstrap warnings: move bootstrap truncation warnings out of the system prompt and into the per-turn prompt body so prompt-cache reuse stays stable when truncation warnings appear or disappear. (#48753) Thanks @scoootscooob and @obviyus.
 - Telegram/DM topic session keys: route named-account DM topics through the same per-account base session key across inbound messages, native commands, and session-state lookups so `/status` and thread recovery stop creating phantom `agent:main:main:thread:...` sessions. (#48204) Thanks @vincentkoc.
 - macOS/node service startup: use `openclaw node start/stop --json` from the Mac app instead of the removed `openclaw service node ...` command shape, so current CLI installs expose the full node exec surface again. (#46843) Fixes #43171. Thanks @Br1an67.
@@ -132,18 +140,6 @@ Docs: https://docs.openclaw.ai
 - Mattermost/DM send: retry transient direct-channel creation failures for DM deliveries, with configurable backoff and per-request timeout. (#42398) Thanks @JonathanJing.
 - Telegram/network: unify API and media fetches under the same sticky IPv4 and pinned-IP fallback chain, and re-validate pinned override addresses against SSRF policy. (#49148) Thanks @obviyus.
 - Agents/prompt composition: append bootstrap truncation warnings to the current-turn prompt and add regression coverage for stable system-prompt cache invariants. (#49237) Thanks @scoootscooob.
-- Gateway/auth: add regression coverage that keeps device-less trusted-proxy Control UI sessions off privileged pairing approval RPCs. Thanks @vincentkoc.
-- Plugins/runtime-api: pin extension runtime-api export seams with explicit guardrail coverage so future surface creep becomes a deliberate diff. Thanks @vincentkoc.
-- Telegram/security: add regression coverage proving pinned fallback host overrides stay bound to Telegram and delegate non-matching hostnames back to the original lookup path. Thanks @vincentkoc.
-- Secrets/exec refs: require explicit `--allow-exec` for `secrets apply` write plans that contain exec SecretRefs/providers, and align audit/configure/apply dry-run behavior to skip exec checks unless opted in to prevent unexpected command side effects. (#49417) Thanks @restriction and @joshavant.
-- Tools/image generation: add bundled fal image generation support so `image_generate` can target `fal/*` models with `FAL_KEY`, including single-image edit flows via FLUX image-to-image. Thanks @vincentkoc.
-
-### Breaking
-
-- Browser/Chrome MCP: remove the legacy Chrome extension relay path, bundled extension assets, `driver: "extension"`, and `browser.relayBindHost`. Run `openclaw doctor --fix` to migrate host-local browser config to `existing-session` / `user`; Docker, headless, sandbox, and remote browser flows still use raw CDP. (#47893) Thanks @vincentkoc.
-- Plugins/runtime: remove the public `openclaw/extension-api` surface with no compatibility shim. Bundled plugins must use injected runtime for host-side operations (for example `api.runtime.agent.runEmbeddedPiAgent`) and any remaining direct imports must come from narrow `openclaw/plugin-sdk/*` subpaths instead of the monolithic SDK root.
-- Tools/image generation: standardize the stock image create/edit path on the core `image_generate` tool. The old `nano-banana-pro` docs/examples are gone; if you previously copied that sample-skill config, switch to `agents.defaults.imageGenerationModel` for built-in image generation or install a separate third-party skill explicitly.
-- Plugins/message discovery: require `ChannelMessageActionAdapter.describeMessageTool(...)` for shared `message` tool discovery. The legacy `listActions`, `getCapabilities`, and `getToolSchema` adapter methods are removed. Plugin authors should migrate message discovery to `describeMessageTool(...)` and keep channel-specific action runtime code inside the owning plugin package. Thanks @gumadeiras.
 
 ## 2026.3.13
 
@@ -159,6 +155,10 @@ Docs: https://docs.openclaw.ai
 - Cron/sessions: add `sessionTarget: "current"` and `session:<id>` support so cron jobs can bind to the creating session or a persistent named session instead of only `main` or `isolated`. Thanks @kkhomej33-netizen and @ImLukeF.
 - Telegram/message send: add `--force-document` so Telegram image and GIF sends can upload as documents without compression. (#45111) Thanks @thepagent.
 
+### Breaking
+
+- **BREAKING:** Agents now load at most one root memory bootstrap file. `MEMORY.md` wins; `memory.md` is only used when `MEMORY.md` is absent. If you intentionally kept both files and depended on both being injected, merge them before upgrade. This also fixes duplicate memory injection on case-insensitive Docker mounts. (#26054) Thanks @Lanfei.
+
 ### Fixes
 
 - Dashboard/chat UI: stop reloading full chat history on every live tool result in dashboard v2 so tool-heavy runs no longer trigger UI freeze/re-render storms while the final event still refreshes persisted history. (#45541) Thanks @BunsDev.
@@ -218,13 +218,8 @@ Docs: https://docs.openclaw.ai
 - Auth/login lockout recovery: clear stale `auth_permanent` and `billing` disabled state for all profiles matching the target provider when `openclaw models auth login` is invoked, so users locked out by expired or revoked OAuth tokens can recover by re-authenticating instead of waiting for the cooldown timer to expire. (#43057)
 - Auto-reply/context-engine compaction: persist the exact embedded-run metadata compaction count for main and followup runner session accounting, so metadata-only auto-compactions no longer undercount multi-compaction runs. (#42629) thanks @uf-hy.
 - Auth/Codex CLI reuse: sync reused Codex CLI credentials into the supported `openai-codex:default` OAuth profile instead of reviving the deprecated `openai-codex:codex-cli` slot, so doctor cleanup no longer loops. (#45353) thanks @Gugu-sugar.
-- Deps/audit: bump the pinned `fast-xml-parser` override to the first patched release so `pnpm audit --prod --audit-level=high` no longer fails on the AWS Bedrock XML builder path. Thanks @vincentkoc.
 - Hooks/after_compaction: forward `sessionFile` for direct/manual compaction events and add `sessionFile` plus `sessionKey` to wired auto-compaction hook context so plugins receive the session metadata already declared in the hook types. (#40781) Thanks @jarimustonen.
 
-### Breaking
-
-- **BREAKING:** Agents now load at most one root memory bootstrap file. `MEMORY.md` wins; `memory.md` is only used when `MEMORY.md` is absent. If you intentionally kept both files and depended on both being injected, merge them before upgrade. This also fixes duplicate memory injection on case-insensitive Docker mounts. (#26054) Thanks @Lanfei.
-
 ## 2026.3.12
 
 ### Changes
@@ -325,6 +320,10 @@ Docs: https://docs.openclaw.ai
 
 ## 2026.3.11
 
+### Security
+
+- Gateway/WebSocket: enforce browser origin validation for all browser-originated connections regardless of whether proxy headers are present, closing a cross-site WebSocket hijacking path in `trusted-proxy` mode that could grant untrusted origins `operator.admin` access. (GHSA-5wcw-8jjv-m286)
+
 ### Changes
 
 - OpenRouter/models: add temporary Hunter Alpha and Healer Alpha entries to the built-in catalog so OpenRouter users can try the new free stealth models during their roughly one-week availability window. (#43642) Thanks @ping-Toven.
@@ -346,6 +345,10 @@ Docs: https://docs.openclaw.ai
 - Mattermost/reply threading: add `channels.mattermost.replyToMode` for channel and group messages so top-level posts can start thread-scoped sessions without the manual reply-then-thread workaround. (#29587) Thanks @teconomix.
 - iOS/push relay: add relay-backed official-build push delivery with App Attest + receipt verification, gateway-bound send delegation, and config-based relay URL setup on the gateway. (#43369) Thanks @ngutman.
 
+### Breaking
+
+- Cron/doctor: tighten isolated cron delivery so cron jobs can no longer notify through ad hoc agent sends or fallback main-session summaries, and add `openclaw doctor --fix` migration for legacy cron storage and legacy notify/webhook delivery metadata. (#40998) Thanks @mbelinky.
+
 ### Fixes
 
 - Windows/install: stop auto-installing `node-llama-cpp` during normal npm CLI installs so `openclaw@latest` no longer fails on Windows while building optional local-embedding dependencies.
@@ -458,14 +461,6 @@ Docs: https://docs.openclaw.ai
 - Feishu/streaming recovery: clear stale `streamingStartPromise` when card creation fails (HTTP 400) so subsequent messages can retry streaming instead of silently dropping all future replies. Fixes #43322.
 - Exec/env sandbox: block JVM agent injection (`JAVA_TOOL_OPTIONS`, `_JAVA_OPTIONS`, `JDK_JAVA_OPTIONS`), Python breakpoint hijack (`PYTHONBREAKPOINT`), and .NET startup hooks (`DOTNET_STARTUP_HOOKS`) from the host exec environment. (#49025)
 
-### Security
-
-- Gateway/WebSocket: enforce browser origin validation for all browser-originated connections regardless of whether proxy headers are present, closing a cross-site WebSocket hijacking path in `trusted-proxy` mode that could grant untrusted origins `operator.admin` access. (GHSA-5wcw-8jjv-m286)
-
-### Breaking
-
-- Cron/doctor: tighten isolated cron delivery so cron jobs can no longer notify through ad hoc agent sends or fallback main-session summaries, and add `openclaw doctor --fix` migration for legacy cron storage and legacy notify/webhook delivery metadata. (#40998) Thanks @mbelinky.
-
 ## 2026.3.8
 
 ### Changes
@@ -578,6 +573,10 @@ Docs: https://docs.openclaw.ai
 - Google/Gemini 3.1 Flash-Lite: add first-class `google/gemini-3.1-flash-lite-preview` support across model-id normalization, default aliases, media-understanding image lookups, Google Gemini CLI forward-compat fallback, and docs.
 - Agents/compaction model override: allow `agents.defaults.compaction.model` to route compaction summarization through a different model than the main session, and document the override across config help/reference surfaces. (#38753) thanks @starbuck100.
 
+### Breaking
+
+- **BREAKING:** Gateway auth now requires explicit `gateway.auth.mode` when both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs). Set `gateway.auth.mode` to `token` or `password` before upgrade to avoid startup/pairing/TUI failures. (#35094) Thanks @joshavant.
+
 ### Fixes
 
 - Models/MiniMax: stop advertising removed `MiniMax-M2.5-Lightning` in built-in provider catalogs, onboarding metadata, and docs; keep the supported fast-tier model as `MiniMax-M2.5-highspeed`.
@@ -903,10 +902,6 @@ Docs: https://docs.openclaw.ai
 - Mattermost/DM media uploads: resolve bare 26-character Mattermost IDs user-first for direct messages so media sends no longer fail with `403 Forbidden` when targets are configured as unprefixed user IDs. (#29925) Thanks @teconomix.
 - Voice-call/OpenAI TTS config parity: add missing `speed`, `instructions`, and `baseUrl` fields to the OpenAI TTS config schema and gate `instructions` to supported models so voice-call overrides validate and route cleanly through core TTS. (#39226) Thanks @ademczuk.
 
-### Breaking
-
-- **BREAKING:** Gateway auth now requires explicit `gateway.auth.mode` when both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs). Set `gateway.auth.mode` to `token` or `password` before upgrade to avoid startup/pairing/TUI failures. (#35094) Thanks @joshavant.
-
 ## 2026.3.2
 
 ### Changes
@@ -935,6 +930,13 @@ Docs: https://docs.openclaw.ai
 - Gateway/input_image MIME validation: sniff uploaded image bytes before MIME allowlist enforcement again so declared image types cannot mask concrete non-image payloads, while keeping HEIC/HEIF normalization behavior scoped to actual HEIC inputs. Thanks @vincentkoc.
 - Zalo Personal plugin (`@openclaw/zalouser`): keep canonical DM routing while preserving legacy DM session continuity on upgrade, and preserve provider-native `g-`/`u-` target ids in outbound send and directory flows so #33992 lands without breaking existing sessions or stored targets. (#33992) Thanks @darkamenosa.
 
+### Breaking
+
+- **BREAKING:** Onboarding now defaults `tools.profile` to `messaging` for new local installs (interactive + non-interactive). New setups no longer start with broad coding/system tools unless explicitly configured.
+- **BREAKING:** ACP dispatch now defaults to enabled unless explicitly disabled (`acp.dispatch.enabled=false`). If you need to pause ACP turn routing while keeping `/acp` controls, set `acp.dispatch.enabled=false`. Docs: https://docs.openclaw.ai/tools/acp-agents
+- **BREAKING:** Plugin SDK removed `api.registerHttpHandler(...)`. Plugins must register explicit HTTP routes via `api.registerHttpRoute({ path, auth, match, handler })`, and dynamic webhook lifecycles should use `registerPluginHttpRoute(...)`.
+- **BREAKING:** Zalo Personal plugin (`@openclaw/zalouser`) no longer depends on external `zca`-compatible CLI binaries (`openzca`, `zca-cli`) for runtime send/listen/login; operators should use `openclaw channels login --channel zalouser` after upgrade to refresh sessions in the new JS-native path.
+
 ### Fixes
 
 - Feishu/Outbound render mode: respect Feishu account `renderMode` in outbound sends so card mode (and auto-detected markdown tables/code blocks) uses markdown card delivery instead of always sending plain text. (#31562) Thanks @arkyu2077.
@@ -1121,13 +1123,6 @@ Docs: https://docs.openclaw.ai
 - Tests/Subagent announce: set `OPENCLAW_TEST_FAST=1` before importing `subagent-announce` format suites so module-level fast-mode constants are captured deterministically on Windows CI, preventing timeout flakes in nested completion announce coverage. (#31370) Thanks @zwffff.
 - Control UI/markdown recursion fallback: catch markdown parser failures and safely render escaped plain-text fallback instead of crashing the Control UI on pathological markdown history payloads. (#36445, fixes #36213) Thanks @BinHPdev.
 
-### Breaking
-
-- **BREAKING:** Onboarding now defaults `tools.profile` to `messaging` for new local installs (interactive + non-interactive). New setups no longer start with broad coding/system tools unless explicitly configured.
-- **BREAKING:** ACP dispatch now defaults to enabled unless explicitly disabled (`acp.dispatch.enabled=false`). If you need to pause ACP turn routing while keeping `/acp` controls, set `acp.dispatch.enabled=false`. Docs: https://docs.openclaw.ai/tools/acp-agents
-- **BREAKING:** Plugin SDK removed `api.registerHttpHandler(...)`. Plugins must register explicit HTTP routes via `api.registerHttpRoute({ path, auth, match, handler })`, and dynamic webhook lifecycles should use `registerPluginHttpRoute(...)`.
-- **BREAKING:** Zalo Personal plugin (`@openclaw/zalouser`) no longer depends on external `zca`-compatible CLI binaries (`openzca`, `zca-cli`) for runtime send/listen/login; operators should use `openclaw channels login --channel zalouser` after upgrade to refresh sessions in the new JS-native path.
-
 ## 2026.3.1
 
 ### Changes
@@ -1155,6 +1150,11 @@ Docs: https://docs.openclaw.ai
 - OpenAI/WebSocket warm-up: add optional OpenAI Responses WebSocket warm-up (`response.create` with `generate:false`), enable it by default for `openai/*`, and expose `params.openaiWsWarmup` for per-model enable/disable control.
 - Agents/Subagents runtime events: replace ad-hoc subagent completion system-message handoff with typed internal completion events (`task_completion`) that are rendered consistently across direct and queued announce paths, with gateway/CLI plumbing for structured `internalEvents`.
 
+### Breaking
+
+- **BREAKING:** Node exec approval payloads now require `systemRunPlan`. `host=node` approval requests without that plan are rejected.
+- **BREAKING:** Node `system.run` execution now pins path-token commands to the canonical executable path (`realpath`) in both allowlist and approval execution flows. Integrations/tests that asserted token-form argv (for example `tr`) must now accept canonical paths (for example `/usr/bin/tr`).
+
 ### Fixes
 
 - Feishu/Streaming card text fidelity: merge throttled/fragmented partial updates without dropping content and avoid newline injection when stitching chunk-style deltas so card-stream output matches final reply text. (#29616) Thanks @HaoHuaqing.
@@ -1249,11 +1249,6 @@ Docs: https://docs.openclaw.ai
 - Signal/Sync message null-handling: treat `syncMessage` presence (including `null`) as sync envelope traffic so replayed sentTranscript payloads cannot bypass loop guards after daemon restart. Landed from contributor PR #31138 by @Sid-Qin. Thanks @Sid-Qin.
 - Infra/fs-safe: sanitize directory-read failures so raw `EISDIR` text never leaks to messaging surfaces, with regression tests for both root-scoped and direct safe reads. Landed from contributor PR #31205 by @polooooo. Thanks @polooooo.
 
-### Breaking
-
-- **BREAKING:** Node exec approval payloads now require `systemRunPlan`. `host=node` approval requests without that plan are rejected.
-- **BREAKING:** Node `system.run` execution now pins path-token commands to the canonical executable path (`realpath`) in both allowlist and approval execution flows. Integrations/tests that asserted token-form argv (for example `tr`) must now accept canonical paths (for example `/usr/bin/tr`).
-
 ## 2026.2.27
 
 ### Changes
@@ -1529,6 +1524,10 @@ Docs: https://docs.openclaw.ai
 - Agents/Config: remind agents to call `config.schema` before config edits or config-field questions to avoid guessing. Thanks @thewilloftheshadow.
 - Dependencies: update workspace dependency pins and lockfile (Bedrock SDK `3.998.0`, `@mariozechner/pi-*` `0.55.1`, TypeScript native preview `7.0.0-dev.20260225.1`) while keeping `@buape/carbon` pinned.
 
+### Breaking
+
+- **BREAKING:** Heartbeat direct/DM delivery default is now `allow` again. To keep DM-blocked behavior from `2026.2.24`, set `agents.defaults.heartbeat.directPolicy: "block"` (or per-agent override).
+
 ### Fixes
 
 - Slack/Identity: thread agent outbound identity (`chat:write.customize` overrides) through the channel reply delivery path so per-agent username, icon URL, and icon emoji are applied to all Slack replies including media messages. (#27134) Thanks @hou-rong.
@@ -1592,10 +1591,6 @@ Docs: https://docs.openclaw.ai
 - Tests/Low-memory stability: disable Vitest `vmForks` by default on low-memory local hosts (`<64 GiB`), keep low-profile extension lane parallelism at 4 workers, and align cron isolated-agent tests with `setSessionRuntimeModel` usage to avoid deterministic suite failures. (#26324) Thanks @ngutman.
 - Feishu/WebSocket proxy: pass a proxy agent to Feishu WS clients from standard proxy environment variables and include plugin-local runtime dependency wiring so websocket mode works in proxy-constrained installs. (#26397) Thanks @colin719.
 
-### Breaking
-
-- **BREAKING:** Heartbeat direct/DM delivery default is now `allow` again. To keep DM-blocked behavior from `2026.2.24`, set `agents.defaults.heartbeat.directPolicy: "block"` (or per-agent override).
-
 ## 2026.2.24
 
 ### Changes
@@ -1606,6 +1601,11 @@ Docs: https://docs.openclaw.ai
 - Security/Audit: add `security.trust_model.multi_user_heuristic` to flag likely shared-user ingress and clarify the personal-assistant trust model, with hardening guidance for intentional multi-user setups (`sandbox.mode="all"`, workspace-scoped FS, reduced tool surface, no personal/private identities on shared runtimes).
 - Dependencies: refresh key runtime and tooling packages across the workspace (Bedrock SDK, pi runtime stack, OpenAI, Google auth, and oxlint/oxfmt), while intentionally keeping `@buape/carbon` pinned.
 
+### Breaking
+
+- **BREAKING:** Heartbeat delivery now blocks direct/DM targets when destination parsing identifies a direct chat (for example `user:<id>`, Telegram user chat IDs, or WhatsApp direct numbers/JIDs). Heartbeat runs still execute, but direct-message delivery is skipped and only non-DM destinations (for example channel/group targets) can receive outbound heartbeat messages.
+- **BREAKING:** Security/Sandbox: block Docker `network: "container:<id>"` namespace-join mode by default for sandbox and sandbox-browser containers. To keep that behavior intentionally, set `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). Thanks @tdjackey for reporting.
+
 ### Fixes
 
 - Routing/Session isolation: harden followup routing so explicit cross-channel origin replies never fall back to the active dispatcher on route failure, preserve queued overflow summary routing metadata (`channel`/`to`/`thread`) across followup drain, and prefer originating channel context over internal provider tags for embedded followup runs. This prevents webchat/control-ui context from hijacking Discord-targeted replies in shared sessions. (#25864) Thanks @Gamedesigner.
@@ -1685,11 +1685,6 @@ Docs: https://docs.openclaw.ai
 - Agents/Compaction: harden summarization prompts to preserve opaque identifiers verbatim (UUIDs, IDs, tokens, host/IP/port, URLs), reducing post-compaction identifier drift and hallucinated identifier reconstruction.
 - Security/Sandbox: canonicalize bind-mount source paths via existing-ancestor realpath so symlink-parent + non-existent-leaf paths cannot bypass allowed-source-roots or blocked-path checks. Thanks @tdjackey.
 
-### Breaking
-
-- **BREAKING:** Heartbeat delivery now blocks direct/DM targets when destination parsing identifies a direct chat (for example `user:<id>`, Telegram user chat IDs, or WhatsApp direct numbers/JIDs). Heartbeat runs still execute, but direct-message delivery is skipped and only non-DM destinations (for example channel/group targets) can receive outbound heartbeat messages.
-- **BREAKING:** Security/Sandbox: block Docker `network: "container:<id>"` namespace-join mode by default for sandbox and sandbox-browser containers. To keep that behavior intentionally, set `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). Thanks @tdjackey for reporting.
-
 ## 2026.2.23
 
 ### Changes
@@ -1704,6 +1699,10 @@ Docs: https://docs.openclaw.ai
 - Agents/Config: support per-agent `params` overrides merged on top of model defaults (including `cacheRetention`) so mixed-traffic agents can tune cache behavior independently. (#17470, #17112) Thanks @rrenamed.
 - Agents/Bootstrap: cache bootstrap file snapshots per session key and clear them on session reset/delete, reducing prompt-cache invalidations from in-session `AGENTS.md`/`MEMORY.md` writes. (#22220) Thanks @anisoptera.
 
+### Breaking
+
+- **BREAKING:** browser SSRF policy now defaults to trusted-network mode (`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork=true` when unset), and canonical config uses `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` instead of `browser.ssrfPolicy.allowPrivateNetwork`. `openclaw doctor --fix` migrates the legacy key automatically.
+
 ### Fixes
 
 - Security/Config: redact sensitive-looking dynamic catchall keys in `config.get` snapshots (for example `env.*` and `skills.entries.*.env.*`) and preserve round-trip restore behavior for those redacted sentinels. Thanks @merc1305.
@@ -1749,10 +1748,6 @@ Docs: https://docs.openclaw.ai
 - Skills/Python: harden skill script packaging and validation edge cases (self-including `.skill` outputs, CRLF frontmatter parsing, strict `--days` validation, and safer image file loading), with expanded Python regression coverage. Thanks @vincentkoc.
 - Skills/Python: add CI + pre-commit linting (`ruff`) and pytest discovery coverage for Python scripts/tests under `skills/`, including package test execution from repo root. Thanks @vincentkoc.
 
-### Breaking
-
-- **BREAKING:** browser SSRF policy now defaults to trusted-network mode (`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork=true` when unset), and canonical config uses `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` instead of `browser.ssrfPolicy.allowPrivateNetwork`. `openclaw doctor --fix` migrates the legacy key automatically.
-
 ## 2026.2.22
 
 ### Changes
@@ -1777,6 +1772,14 @@ Docs: https://docs.openclaw.ai
 - Skills: remove bundled `food-order` skill from this repo; manage/install it from ClawHub instead.
 - Docs/Subagents: make thread-bound session guidance channel-first instead of Discord-specific, and list thread-supporting channels explicitly. (#23589) Thanks @osolmaz.
 
+### Breaking
+
+- **BREAKING:** removed Google Antigravity provider support and the bundled `google-antigravity-auth` plugin. Existing `google-antigravity/*` model/profile configs no longer work; migrate to `google-gemini-cli` or other supported providers.
+- **BREAKING:** tool-failure replies now hide raw error details by default. OpenClaw still sends a failure summary, but detailed error suffixes (for example provider/runtime messages and local path fragments) now require `/verbose on` or `/verbose full`.
+- **BREAKING:** CLI local onboarding now sets `session.dmScope` to `per-channel-peer` by default for new/implicit DM scope configuration. If you depend on shared DM continuity across senders, explicitly set `session.dmScope` to `main`. (#23468) Thanks @bmendonca3.
+- **BREAKING:** unify channel preview-streaming config to `channels.<channel>.streaming` with enum values `off | partial | block | progress`, and move Slack native stream toggle to `channels.slack.nativeStreaming`. Legacy keys (`streamMode`, Slack boolean `streaming`) are still read and migrated by `openclaw doctor --fix`, but canonical saved config/docs now use the unified names.
+- **BREAKING:** remove legacy Gateway device-auth signature `v1`. Device-auth clients must now sign `v2` payloads with the per-connection `connect.challenge` nonce and send `device.nonce`; nonce-less connects are rejected.
+
 ### Fixes
 
 - Sessions/Resilience: ignore invalid persisted `sessionFile` metadata and fall back to the derived safe transcript path instead of aborting session resolution for handlers and tooling. (#16061) Thanks @haoyifan and @vincentkoc.
@@ -2003,14 +2006,6 @@ Docs: https://docs.openclaw.ai
 - Gateway/Daemon: verify gateway health after daemon restart.
 - Agents/UI text: stop rewriting normal assistant billing/payment language outside explicit error contexts. (#17834) Thanks @niceysam.
 
-### Breaking
-
-- **BREAKING:** removed Google Antigravity provider support and the bundled `google-antigravity-auth` plugin. Existing `google-antigravity/*` model/profile configs no longer work; migrate to `google-gemini-cli` or other supported providers.
-- **BREAKING:** tool-failure replies now hide raw error details by default. OpenClaw still sends a failure summary, but detailed error suffixes (for example provider/runtime messages and local path fragments) now require `/verbose on` or `/verbose full`.
-- **BREAKING:** CLI local onboarding now sets `session.dmScope` to `per-channel-peer` by default for new/implicit DM scope configuration. If you depend on shared DM continuity across senders, explicitly set `session.dmScope` to `main`. (#23468) Thanks @bmendonca3.
-- **BREAKING:** unify channel preview-streaming config to `channels.<channel>.streaming` with enum values `off | partial | block | progress`, and move Slack native stream toggle to `channels.slack.nativeStreaming`. Legacy keys (`streamMode`, Slack boolean `streaming`) are still read and migrated by `openclaw doctor --fix`, but canonical saved config/docs now use the unified names.
-- **BREAKING:** remove legacy Gateway device-auth signature `v1`. Device-auth clients must now sign `v2` payloads with the per-connection `connect.challenge` nonce and send `device.nonce`; nonce-less connects are rejected.
-
 ## 2026.2.21
 
 ### Changes
@@ -2659,6 +2654,10 @@ Docs: https://docs.openclaw.ai
 - Onboarding/Providers: add first-class Hugging Face Inference provider support (provider wiring, onboarding auth choice/API key flow, and default-model selection), and preserve Hugging Face auth intent in auth-choice remapping (`tokenProvider=huggingface` with `authChoice=apiKey`) while skipping env-override prompts when an explicit token is provided. (#13472) Thanks @Josephrp.
 - Onboarding/Providers: add `minimax-api-key-cn` auth choice for the MiniMax China API endpoint. (#15191) Thanks @liuy.
 
+### Breaking
+
+- Config/State: removed legacy `.moltbot` auto-detection/migration and `moltbot.json` config candidates. If you still have state/config under `~/.moltbot`, move it to `~/.openclaw` (recommended) or set `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH` explicitly.
+
 ### Fixes
 
 - Gateway/Auth: add trusted-proxy mode hardening follow-ups by keeping `OPENCLAW_GATEWAY_*` env compatibility, auto-normalizing invalid setup combinations in interactive `gateway configure` (trusted-proxy forces `bind=lan` and disables Tailscale serve/funnel), and suppressing shared-secret/rate-limit audit findings that do not apply to trusted-proxy deployments. (#15940) Thanks @nickytonline.
@@ -2761,10 +2760,6 @@ Docs: https://docs.openclaw.ai
 - Docs/Mermaid: remove hardcoded Mermaid init theme blocks from four docs diagrams so dark mode inherits readable theme defaults. (#15157) Thanks @heytulsiprasad.
 - Security/Pairing: generate 256-bit base64url device and node pairing tokens and use byte-safe constant-time verification to avoid token-compare edge-case failures. (#16535) Thanks @FaizanKolega, @gumadeiras.
 
-### Breaking
-
-- Config/State: removed legacy `.moltbot` auto-detection/migration and `moltbot.json` config candidates. If you still have state/config under `~/.moltbot`, move it to `~/.openclaw` (recommended) or set `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH` explicitly.
-
 ## 2026.2.12
 
 ### Changes
@@ -2776,6 +2771,10 @@ Docs: https://docs.openclaw.ai
 - Discord: add role-based allowlists and role-based agent routing. (#10650) Thanks @Minidoracat.
 - Config: avoid redacting `maxTokens`-like fields during config snapshot redaction, preventing round-trip validation failures in `/config`. (#14006) Thanks @constansino.
 
+### Breaking
+
+- Hooks: `POST /hooks/agent` now rejects payload `sessionKey` overrides by default. To keep fixed hook context, set `hooks.defaultSessionKey` (recommended with `hooks.allowedSessionKeyPrefixes: ["hook:"]`). If you need legacy behavior, explicitly set `hooks.allowRequestSessionKey: true`. Thanks @alpernae for reporting.
+
 ### Fixes
 
 - Gateway/OpenResponses: harden URL-based `input_file`/`input_image` handling with explicit SSRF deny policy, hostname allowlists (`files.urlAllowlist` / `images.urlAllowlist`), per-request URL input caps (`maxUrlParts`), blocked-fetch audit logging, and regression coverage/docs updates.
@@ -2858,10 +2857,6 @@ Docs: https://docs.openclaw.ai
 - Tests: update thread ID handling in Slack message collection tests. (#14108) Thanks @swizzmagik.
 - Update/Daemon: fix post-update restart compatibility by generating `dist/cli/daemon-cli.js` with alias-aware exports from hashed daemon bundles, preventing `registerDaemonCli` import failures during `openclaw update`.
 
-### Breaking
-
-- Hooks: `POST /hooks/agent` now rejects payload `sessionKey` overrides by default. To keep fixed hook context, set `hooks.defaultSessionKey` (recommended with `hooks.allowedSessionKeyPrefixes: ["hook:"]`). If you need legacy behavior, explicitly set `hooks.allowRequestSessionKey: true`. Thanks @alpernae for reporting.
-
 ## 2026.2.9
 
 ### Added
@@ -2951,12 +2946,6 @@ Docs: https://docs.openclaw.ai
 
 ## 2026.2.6
 
-### Added
-
-- Cron: run history deep-links to session chat from the dashboard. (#10776) Thanks @tyler6204.
-- Cron: per-run session keys in run log entries and default labels for cron sessions. (#10776) Thanks @tyler6204.
-- Cron: legacy payload field compatibility (`deliver`, `channel`, `to`, `bestEffortDeliver`) in schema. (#10776) Thanks @tyler6204.
-
 ### Changes
 
 - Cron: default `wakeMode` is now `"now"` for new jobs (was `"next-heartbeat"`). (#10776) Thanks @tyler6204.
@@ -2972,6 +2961,12 @@ Docs: https://docs.openclaw.ai
 - CI: optimize pipeline throughput (macOS consolidation, Windows perf, workflow concurrency). (#10784) Thanks @mcaxtr.
 - Agents: bump pi-mono to 0.52.7; add embedded forward-compat fallback for Opus 4.6 model ids.
 
+### Added
+
+- Cron: run history deep-links to session chat from the dashboard. (#10776) Thanks @tyler6204.
+- Cron: per-run session keys in run log entries and default labels for cron sessions. (#10776) Thanks @tyler6204.
+- Cron: legacy payload field compatibility (`deliver`, `channel`, `to`, `bestEffortDeliver`) in schema. (#10776) Thanks @tyler6204.
+
 ### Fixes
 
 - TTS: add missing OpenAI voices (ballad, cedar, juniper, marin, verse) to the allowlist so they are recognized instead of silently falling back to Edge TTS. (#2393)
@@ -3270,6 +3265,10 @@ Docs: https://docs.openclaw.ai
 - Docs: keep docs header sticky so navbar stays visible while scrolling. (#2445) Thanks @chenyuan99.
 - Docs: update exe.dev install instructions. (#https://github.com/openclaw/openclaw/pull/3047) Thanks @zackerthescar.
 
+### Breaking
+
+- **BREAKING:** Gateway auth mode "none" is removed; gateway now requires token/password (Tailscale Serve identity still allowed).
+
 ### Fixes
 
 - Skills: update session-logs paths to use ~/.openclaw. (#4502) Thanks @bonald.
@@ -3322,10 +3321,6 @@ Docs: https://docs.openclaw.ai
 - Gateway: treat loopback + non-local Host connections as remote unless trusted proxy headers are present.
 - Onboarding: remove unsupported gateway auth "off" choice from onboarding/configure flows and CLI flags.
 
-### Breaking
-
-- **BREAKING:** Gateway auth mode "none" is removed; gateway now requires token/password (Tailscale Serve identity still allowed).
-
 ## 2026.1.24-3
 
 ### Fixes
@@ -3557,6 +3552,11 @@ Docs: https://docs.openclaw.ai
 - Docs: add /model allowlist troubleshooting note. (#1405)
 - Docs: add per-message Gmail search example for gog. (#1220) Thanks @mbelinky.
 
+### Breaking
+
+- **BREAKING:** Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set `gateway.controlUi.allowInsecureAuth: true` to allow token-only auth. https://docs.openclaw.ai/web/control-ui#insecure-http
+- **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.
+
 ### Fixes
 
 - Nodes/macOS: prompt on allowlist miss for node exec approvals, persist allowlist decisions, and flatten node invoke errors. (#1394) Thanks @ngutman.
@@ -3579,11 +3579,6 @@ Docs: https://docs.openclaw.ai
 - macOS: default distribution packaging to universal binaries. (#1396) Thanks @JustYannicc.
 - Embedded runner: forward sender identity into attempt execution so Feishu doc auto-grant receives requester context again. (#32915) Thanks @cszhouwei.
 
-### Breaking
-
-- **BREAKING:** Control UI now rejects insecure HTTP without device identity by default. Use HTTPS (Tailscale Serve) or set `gateway.controlUi.allowInsecureAuth: true` to allow token-only auth. https://docs.openclaw.ai/web/control-ui#insecure-http
-- **BREAKING:** Envelope and system event timestamps now default to host-local time (was UTC) so agents don’t have to constantly convert.
-
 ## 2026.1.20
 
 ### Changes
@@ -3665,6 +3660,10 @@ Docs: https://docs.openclaw.ai
 - macOS: stop syncing Peekaboo in postinstall.
 - Swabble: use the tagged Commander Swift package release.
 
+### Breaking
+
+- **BREAKING:** Reject invalid/unknown config entries and refuse to start the gateway for safety. Run `openclaw doctor --fix` to repair, then update plugins (`openclaw plugins update`) if you use any.
+
 ### Fixes
 
 - Discovery: shorten Bonjour DNS-SD service type to `_moltbot-gw._tcp` and update discovery clients/docs.
@@ -3763,10 +3762,6 @@ Docs: https://docs.openclaw.ai
 
 Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @NicholaiVogel, @RyanLisse, @ThePickle31, @VACInc, @Whoaa512, @YuriNachos, @aaronveklabs, @abdaraxus, @alauppe, @ameno-, @artuskg, @austinm911, @bradleypriest, @cheeeee, @dougvk, @fogboots, @gnarco, @gumadeiras, @jdrhyne, @joelklabo, @longmaba, @mukhtharcm, @odysseus0, @oscargavin, @rhjoh, @sebslight, @sibbl, @sleontenko, @steipete, @suminhthanh, @thewilloftheshadow, @tyler6204, @vignesh07, @visionik, @ysqander, @zerone0x.
 
-### Breaking
-
-- **BREAKING:** Reject invalid/unknown config entries and refuse to start the gateway for safety. Run `openclaw doctor --fix` to repair, then update plugins (`openclaw plugins update`) if you use any.
-
 ## 2026.1.16-2
 
 ### Changes
@@ -3785,6 +3780,15 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Sessions: add `session.identityLinks` for cross-platform DM session li nking. (#1033) — thanks @thewilloftheshadow. https://docs.openclaw.ai/concepts/session
 - Web search: add `country`/`language` parameters (schema + Brave API) and docs. (#1046) — thanks @YuriNachos. https://docs.openclaw.ai/tools/web
 
+### Breaking
+
+- **BREAKING:** `openclaw message` and message tool now require `target` (dropping `to`/`channelId` for destinations). (#1034) — thanks @tobalsan.
+- **BREAKING:** Channel auth now prefers config over env for Discord/Telegram/Matrix (env is fallback only). (#1040) — thanks @thewilloftheshadow.
+- **BREAKING:** Drop legacy `chatType: "room"` support; use `chatType: "channel"`.
+- **BREAKING:** remove legacy provider-specific target resolution fallbacks; target resolution is centralized with plugin hints + directory lookups.
+- **BREAKING:** `openclaw hooks` is now `openclaw webhooks`; hooks live under `openclaw hooks`. https://docs.openclaw.ai/cli/webhooks
+- **BREAKING:** `openclaw plugins install <path>` now copies into `~/.openclaw/extensions` (use `--link` to keep path-based loading).
+
 ### Changes
 
 - Plugins: ship bundled plugins disabled by default and allow overrides by installed versions. (#1066) — thanks @ItzR3NO.
@@ -3876,15 +3880,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Discord: preserve whitespace when chunking long lines so message splits keep spacing intact.
 - Skills: fix skills watcher ignored list typing (tsc).
 
-### Breaking
-
-- **BREAKING:** `openclaw message` and message tool now require `target` (dropping `to`/`channelId` for destinations). (#1034) — thanks @tobalsan.
-- **BREAKING:** Channel auth now prefers config over env for Discord/Telegram/Matrix (env is fallback only). (#1040) — thanks @thewilloftheshadow.
-- **BREAKING:** Drop legacy `chatType: "room"` support; use `chatType: "channel"`.
-- **BREAKING:** remove legacy provider-specific target resolution fallbacks; target resolution is centralized with plugin hints + directory lookups.
-- **BREAKING:** `openclaw hooks` is now `openclaw webhooks`; hooks live under `openclaw hooks`. https://docs.openclaw.ai/cli/webhooks
-- **BREAKING:** `openclaw plugins install <path>` now copies into `~/.openclaw/extensions` (use `--link` to keep path-based loading).
-
 ## 2026.1.15
 
 ### Highlights
@@ -3894,6 +3889,11 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Heartbeat: per-agent configuration + 24h duplicate suppression. (#980) — thanks @voidserf.
 - Security: audit warns on weak model tiers; app nodes store auth tokens encrypted (Keychain/SecurePrefs).
 
+### Breaking
+
+- **BREAKING:** iOS minimum version is now 18.0 to support Textual markdown rendering in native chat. (#702)
+- **BREAKING:** Microsoft Teams is now a plugin; install `@openclaw/msteams` via `openclaw plugins install @openclaw/msteams`.
+
 ### Changes
 
 - UI/Apps: move channel/config settings to schema-driven forms and rename Connections → Channels. (#1040) — thanks @thewilloftheshadow.
@@ -3966,11 +3966,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Fix: allow local Tailscale Serve hostnames without treating tailnet clients as direct. (#885) — thanks @oswalpalash.
 - Fix: reset sessions after role-ordering conflicts to recover from consecutive user turns. (#998)
 
-### Breaking
-
-- **BREAKING:** iOS minimum version is now 18.0 to support Textual markdown rendering in native chat. (#702)
-- **BREAKING:** Microsoft Teams is now a plugin; install `@openclaw/msteams` via `openclaw plugins install @openclaw/msteams`.
-
 ## 2026.1.14-1
 
 ### Highlights
@@ -4107,6 +4102,10 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Gateway: allow Tailscale Serve identity headers to satisfy token auth; rebuild Control UI assets when protocol schema is newer. (#823) — thanks @roshanasingh4; (#786) — thanks @meaningfool.
 - Heartbeat: default `ackMaxChars` to 300 so short `HEARTBEAT_OK` replies stay internal.
 
+### Installer
+
+- Install: run `openclaw doctor --non-interactive` after git installs/updates and nudge daemon restarts when detected.
+
 ### Fixes
 
 - Doctor: warn on pnpm workspace mismatches, missing Control UI assets, and missing tsx binaries; offer UI rebuilds.
@@ -4132,10 +4131,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Tools/UI: harden tool input schemas for strict providers; drop null-only union variants for Gemini schema cleanup; treat `maxChars: 0` as unlimited; keep TUI last streamed response instead of "(no output)". (#782) — thanks @AbhisekBasu1; (#796) — thanks @gabriel-trigo; (#747) — thanks @thewilloftheshadow.
 - Connections UI: polish multi-account account cards. (#816) — thanks @steipete.
 
-### Installer
-
-- Install: run `openclaw doctor --non-interactive` after git installs/updates and nudge daemon restarts when detected.
-
 ### Maintenance
 
 - Dependencies: bump Pi packages to 0.45.3 and refresh patched pi-ai.
@@ -4187,6 +4182,15 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Gateway: require `client.id` in WebSocket connect params; use `client.instanceId` for presence de-dupe; update docs/tests.
 - macOS: remove the attach-only gateway setting; local mode now always manages launchd while still attaching to an existing gateway if present.
 
+### Installer
+
+- Postinstall: replace `git apply` with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.
+- Postinstall: skip pnpm patch fallback when the new patcher is active.
+- Installer tests: add root+non-root docker smokes, CI workflow to fetch openclaw.ai scripts and run install sh/cli with onboarding skipped.
+- Installer UX: support `CLAWDBOT_NO_ONBOARD=1` for non-interactive installs; fix npm prefix on Linux and auto-install git.
+- Installer UX: add `install.sh --help` with flags/env and git install hint.
+- Installer UX: add `--install-method git|npm` and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).
+
 ### Fixes
 
 - Models/Onboarding: configure MiniMax (minimax.io) via Anthropic-compatible `/anthropic` endpoint by default (keep `minimax-api` as a legacy alias).
@@ -4225,15 +4229,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Sandbox/Gateway: treat `agent:<id>:main` as a main-session alias when `session.mainKey` is customized (backwards compatible).
 - Auto-reply: fast-path allowlisted slash commands (inline `/help`/`/commands`/`/status`/`/whoami` stripped before model).
 
-### Installer
-
-- Postinstall: replace `git apply` with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.
-- Postinstall: skip pnpm patch fallback when the new patcher is active.
-- Installer tests: add root+non-root docker smokes, CI workflow to fetch openclaw.ai scripts and run install sh/cli with onboarding skipped.
-- Installer UX: support `CLAWDBOT_NO_ONBOARD=1` for non-interactive installs; fix npm prefix on Linux and auto-install git.
-- Installer UX: add `install.sh --help` with flags/env and git install hint.
-- Installer UX: add `--install-method git|npm` and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).
-
 ## 2026.1.10
 
 ### Highlights
@@ -4342,6 +4337,11 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Auto-reply + status: block-streaming controls, reasoning handling, usage/cost reporting.
 - Control UI/TUI: queued messages, session links, reasoning view, mobile polish, logs UX.
 
+### Breaking
+
+- CLI: `openclaw message` now subcommands (`message send|poll|...`) and requires `--provider` unless only one provider configured.
+- Commands/Tools: `/restart` and gateway restart tool disabled by default; enable with `commands.restart=true`.
+
 ### New Features and Changes
 
 - Models/Auth: OpenCode Zen onboarding (#623) — thanks @magimetal; MiniMax Anthropic-compatible API + hosted onboarding (#590, #495) — thanks @mneves75, @tobiasbischoff.
@@ -4383,11 +4383,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Onboarding/Configure: QuickStart single-select provider picker; avoid Codex CLI false-expiry warnings; clarify WhatsApp owner prompt; fix Minimax hosted onboarding (agents.defaults + msteams heartbeat target); remove configure Control UI prompt; honor gateway --dev flag.
 - Agent loop: guard overflow compaction throws and restore compaction hooks for engine-owned context engines. (#41361) — thanks @davidrudduck
 
-### Breaking
-
-- CLI: `openclaw message` now subcommands (`message send|poll|...`) and requires `--provider` unless only one provider configured.
-- Commands/Tools: `/restart` and gateway restart tool disabled by default; enable with `commands.restart=true`.
-
 ### Maintenance
 
 - Dependencies: bump pi-\* stack to 0.42.2.
@@ -4407,18 +4402,6 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Control UI: logs tab, streaming stability, focus mode, and large-output rendering fixes.
 - CLI/Gateway/Doctor: daemon/logs/status, auth migration, and diagnostics significantly expanded.
 
-### Fixes
-
-- **CLI/Gateway/Doctor:** daemon runtime selection + improved logs/status/health/errors; auth/password handling for local CLI; richer close/timeout details; auto-migrate legacy config/sessions/state; integrity checks + repair prompts; `--yes`/`--non-interactive`; `--deep` gateway scans; better restart/service hints.
-- **Agent loop + compaction:** compaction/pruning tuning, overflow handling, safer bootstrap context, and per-provider threading/confirmations; opt-in tool-result pruning + compact tracking.
-- **Sandbox + tools:** per-agent sandbox overrides, workspaceAccess controls, session tool visibility, tool policy overrides, process isolation, and tool schema/timeout/reaction unification.
-- **Providers (Telegram/WhatsApp/Discord/Slack/Signal/iMessage):** retry/backoff, threading, reactions, media groups/attachments, mention gating, typing behavior, and error/log stability; long polling + forum topic isolation for Telegram.
-- **Gateway/CLI UX:** `openclaw logs`, cron list colors/aliases, docs search, agents list/add/delete flows, status usage snapshots, runtime/auth source display, and `/status`/commands auth unification.
-- **Control UI/Web:** logs tab, focus mode polish, config form resilience, streaming stability, tool output caps, windowed chat history, and reconnect/password URL auth.
-- **macOS/Android/TUI/Build:** macOS gateway races, QR bundling, JSON5 config safety, Voice Wake hardening; Android EXIF rotation + APK naming/versioning; TUI key handling; tooling/bundling fixes.
-- **Packaging/compat:** npm dist folder coverage, Node 25 qrcode-terminal import fixes, Bun/Playwright/WebSocket patches, and Docker Bun install.
-- **Docs:** new FAQ/ClawHub/config examples/showcase entries and clarified auth, sandbox, and systemd docs.
-
 ### Breaking
 
 - **SECURITY (update ASAP):** inbound DMs are now **locked down by default** on Telegram/WhatsApp/Signal/iMessage/Discord/Slack.
@@ -4434,6 +4417,18 @@ Thanks @AlexMikhalev, @CoreyH, @John-Rood, @KrauseFx, @MaudeBot, @Nachx639, @Nic
 - Auto-reply: removed `autoReply` from Discord/Slack/Telegram channel configs; use `requireMention` instead (Telegram topics now support `requireMention` overrides).
 - CLI: remove `update`, `gateway-daemon`, `gateway {install|uninstall|start|stop|restart|daemon status|wake|send|agent}`, and `telegram` commands; move `login/logout` to `providers login/logout` (top-level aliases hidden); use `daemon` for service control, `send`/`agent`/`wake` for RPC, and `nodes canvas` for canvas ops.
 
+### Fixes
+
+- **CLI/Gateway/Doctor:** daemon runtime selection + improved logs/status/health/errors; auth/password handling for local CLI; richer close/timeout details; auto-migrate legacy config/sessions/state; integrity checks + repair prompts; `--yes`/`--non-interactive`; `--deep` gateway scans; better restart/service hints.
+- **Agent loop + compaction:** compaction/pruning tuning, overflow handling, safer bootstrap context, and per-provider threading/confirmations; opt-in tool-result pruning + compact tracking.
+- **Sandbox + tools:** per-agent sandbox overrides, workspaceAccess controls, session tool visibility, tool policy overrides, process isolation, and tool schema/timeout/reaction unification.
+- **Providers (Telegram/WhatsApp/Discord/Slack/Signal/iMessage):** retry/backoff, threading, reactions, media groups/attachments, mention gating, typing behavior, and error/log stability; long polling + forum topic isolation for Telegram.
+- **Gateway/CLI UX:** `openclaw logs`, cron list colors/aliases, docs search, agents list/add/delete flows, status usage snapshots, runtime/auth source display, and `/status`/commands auth unification.
+- **Control UI/Web:** logs tab, focus mode polish, config form resilience, streaming stability, tool output caps, windowed chat history, and reconnect/password URL auth.
+- **macOS/Android/TUI/Build:** macOS gateway races, QR bundling, JSON5 config safety, Voice Wake hardening; Android EXIF rotation + APK naming/versioning; TUI key handling; tooling/bundling fixes.
+- **Packaging/compat:** npm dist folder coverage, Node 25 qrcode-terminal import fixes, Bun/Playwright/WebSocket patches, and Docker Bun install.
+- **Docs:** new FAQ/ClawHub/config examples/showcase entries and clarified auth, sandbox, and systemd docs.
+
 ### Maintenance
 
 - Skills additions (Himalaya email, CodexBar, 1Password).

docs/.generated/config-baseline.json

@@ -23200,56 +23200,6 @@
       "tags": [],
       "hasChildren": false
     },
-    {
-      "path": "channels.mattermost.accounts.*.dmChannelRetry",
-      "kind": "channel",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": true
-    },
-    {
-      "path": "channels.mattermost.accounts.*.dmChannelRetry.initialDelayMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.accounts.*.dmChannelRetry.maxDelayMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.accounts.*.dmChannelRetry.maxRetries",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.accounts.*.dmChannelRetry.timeoutMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
     {
       "path": "channels.mattermost.accounts.*.dmPolicy",
       "kind": "channel",
@@ -23759,56 +23709,6 @@
       "tags": [],
       "hasChildren": false
     },
-    {
-      "path": "channels.mattermost.dmChannelRetry",
-      "kind": "channel",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": true
-    },
-    {
-      "path": "channels.mattermost.dmChannelRetry.initialDelayMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.dmChannelRetry.maxDelayMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.dmChannelRetry.maxRetries",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "channels.mattermost.dmChannelRetry.timeoutMs",
-      "kind": "channel",
-      "type": "integer",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
     {
       "path": "channels.mattermost.dmPolicy",
       "kind": "channel",
@@ -37701,13 +37601,12 @@
       "path": "channels.zalouser.accounts.*.groupPolicy",
       "kind": "channel",
       "type": "string",
-      "required": true,
+      "required": false,
       "enumValues": [
         "open",
         "disabled",
         "allowlist"
       ],
-      "defaultValue": "allowlist",
       "deprecated": false,
       "sensitive": false,
       "tags": [],
@@ -38004,13 +37903,12 @@
       "path": "channels.zalouser.groupPolicy",
       "kind": "channel",
       "type": "string",
-      "required": true,
+      "required": false,
       "enumValues": [
         "open",
         "disabled",
         "allowlist"
       ],
-      "defaultValue": "allowlist",
       "deprecated": false,
       "sensitive": false,
       "tags": [],
@@ -39801,7 +39699,7 @@
         "network"
       ],
       "label": "Control UI Allowed Origins",
-      "help": "Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com). Required for non-loopback Control UI deployments unless dangerous Host-header fallback is explicitly enabled. Setting [\"*\"] means allow any browser origin and should be avoided outside tightly controlled local testing.",
+      "help": "Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com). Required for non-loopback Control UI deployments unless dangerous Host-header fallback is explicitly enabled.",
       "hasChildren": true
     },
     {
@@ -41140,7 +41038,7 @@
         "access"
       ],
       "label": "Hooks Allowed Agent IDs",
-      "help": "Allowlist of agent IDs that hook mappings are allowed to target when selecting execution agents. Use this to constrain automation events to dedicated service agents and reduce blast radius if a hook token is exposed.",
+      "help": "Allowlist of agent IDs that hook mappings are allowed to target when selecting execution agents. Use this to constrain automation events to dedicated service agents.",
       "hasChildren": true
     },
     {
@@ -42258,7 +42156,7 @@
         "security"
       ],
       "label": "Hooks Auth Token",
-      "help": "Shared bearer token checked by hooks ingress for request authentication before mappings run. Treat holders as full-trust callers for the hook ingress surface, not as a separate non-owner role. Use environment substitution and rotate regularly when webhook endpoints are internet-accessible.",
+      "help": "Shared bearer token checked by hooks ingress for request authentication before mappings run. Use environment substitution and rotate regularly when webhook endpoints are internet-accessible.",
       "hasChildren": false
     },
     {
@@ -46371,127 +46269,6 @@
       "help": "Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.",
       "hasChildren": false
     },
-    {
-      "path": "plugins.entries.chutes",
-      "kind": "plugin",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "advanced"
-      ],
-      "label": "@openclaw/chutes-provider",
-      "help": "OpenClaw Chutes.ai provider plugin (plugin: chutes)",
-      "hasChildren": true
-    },
-    {
-      "path": "plugins.entries.chutes.config",
-      "kind": "plugin",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "advanced"
-      ],
-      "label": "@openclaw/chutes-provider Config",
-      "help": "Plugin-defined config payload for chutes.",
-      "hasChildren": false
-    },
-    {
-      "path": "plugins.entries.chutes.enabled",
-      "kind": "plugin",
-      "type": "boolean",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "advanced"
-      ],
-      "label": "Enable @openclaw/chutes-provider",
-      "hasChildren": false
-    },
-    {
-      "path": "plugins.entries.chutes.hooks",
-      "kind": "plugin",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "advanced"
-      ],
-      "label": "Plugin Hook Policy",
-      "help": "Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.",
-      "hasChildren": true
-    },
-    {
-      "path": "plugins.entries.chutes.hooks.allowPromptInjection",
-      "kind": "plugin",
-      "type": "boolean",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "access"
-      ],
-      "label": "Allow Prompt Injection Hooks",
-      "help": "Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.",
-      "hasChildren": false
-    },
-    {
-      "path": "plugins.entries.chutes.subagent",
-      "kind": "plugin",
-      "type": "object",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "advanced"
-      ],
-      "label": "Plugin Subagent Policy",
-      "help": "Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.",
-      "hasChildren": true
-    },
-    {
-      "path": "plugins.entries.chutes.subagent.allowedModels",
-      "kind": "plugin",
-      "type": "array",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "access"
-      ],
-      "label": "Plugin Subagent Allowed Models",
-      "help": "Allowed override targets for trusted plugin subagent runs as canonical \"provider/model\" refs. Use \"*\" only when you intentionally allow any model.",
-      "hasChildren": true
-    },
-    {
-      "path": "plugins.entries.chutes.subagent.allowedModels.*",
-      "kind": "plugin",
-      "type": "string",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [],
-      "hasChildren": false
-    },
-    {
-      "path": "plugins.entries.chutes.subagent.allowModelOverride",
-      "kind": "plugin",
-      "type": "boolean",
-      "required": false,
-      "deprecated": false,
-      "sensitive": false,
-      "tags": [
-        "access"
-      ],
-      "label": "Allow Plugin Subagent Model Override",
-      "help": "Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.",
-      "hasChildren": false
-    },
     {
       "path": "plugins.entries.cloudflare-ai-gateway",
       "kind": "plugin",

docs/.generated/config-baseline.jsonl

@@ -1,4 +1,4 @@
-{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5476}
+{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5457}
 {"recordType":"path","path":"acp","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"ACP","help":"ACP runtime controls for enabling dispatch, selecting backends, constraining allowed agent targets, and tuning streamed turn projection behavior.","hasChildren":true}
 {"recordType":"path","path":"acp.allowedAgents","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"ACP Allowed Agents","help":"Allowlist of ACP target agent ids permitted for ACP runtime sessions. Empty means no additional allowlist restriction.","hasChildren":true}
 {"recordType":"path","path":"acp.allowedAgents.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
@@ -2086,11 +2086,6 @@
 {"recordType":"path","path":"channels.mattermost.accounts.*.commands.nativeSkills","kind":"channel","type":["boolean","string"],"required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.accounts.*.configWrites","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.accounts.*.dangerouslyAllowNameMatching","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.accounts.*.dmChannelRetry","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
-{"recordType":"path","path":"channels.mattermost.accounts.*.dmChannelRetry.initialDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.accounts.*.dmChannelRetry.maxDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.accounts.*.dmChannelRetry.maxRetries","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.accounts.*.dmChannelRetry.timeoutMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.accounts.*.dmPolicy","kind":"channel","type":"string","required":true,"enumValues":["pairing","allowlist","open","disabled"],"defaultValue":"pairing","deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.accounts.*.enabled","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.accounts.*.groupAllowFrom","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
@@ -2135,11 +2130,6 @@
 {"recordType":"path","path":"channels.mattermost.configWrites","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network"],"label":"Mattermost Config Writes","help":"Allow Mattermost to write config in response to channel events/commands (default: true).","hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.dangerouslyAllowNameMatching","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.defaultAccount","kind":"channel","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.dmChannelRetry","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
-{"recordType":"path","path":"channels.mattermost.dmChannelRetry.initialDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.dmChannelRetry.maxDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.dmChannelRetry.maxRetries","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.mattermost.dmChannelRetry.timeoutMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.dmPolicy","kind":"channel","type":"string","required":true,"enumValues":["pairing","allowlist","open","disabled"],"defaultValue":"pairing","deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.enabled","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.mattermost.groupAllowFrom","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
@@ -3408,7 +3398,7 @@
 {"recordType":"path","path":"channels.zalouser.accounts.*.enabled","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.zalouser.accounts.*.groupAllowFrom","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.accounts.*.groupAllowFrom.*","kind":"channel","type":["number","string"],"required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.zalouser.accounts.*.groupPolicy","kind":"channel","type":"string","required":true,"enumValues":["open","disabled","allowlist"],"defaultValue":"allowlist","deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
+{"recordType":"path","path":"channels.zalouser.accounts.*.groupPolicy","kind":"channel","type":"string","required":false,"enumValues":["open","disabled","allowlist"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.zalouser.accounts.*.groups","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.accounts.*.groups.*","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.accounts.*.groups.*.allow","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
@@ -3436,7 +3426,7 @@
 {"recordType":"path","path":"channels.zalouser.enabled","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.zalouser.groupAllowFrom","kind":"channel","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.groupAllowFrom.*","kind":"channel","type":["number","string"],"required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"channels.zalouser.groupPolicy","kind":"channel","type":"string","required":true,"enumValues":["open","disabled","allowlist"],"defaultValue":"allowlist","deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
+{"recordType":"path","path":"channels.zalouser.groupPolicy","kind":"channel","type":"string","required":false,"enumValues":["open","disabled","allowlist"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.zalouser.groups","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.groups.*","kind":"channel","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":true}
 {"recordType":"path","path":"channels.zalouser.groups.*.allow","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
@@ -3573,7 +3563,7 @@
 {"recordType":"path","path":"gateway.channelMaxRestartsPerHour","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["network","performance"],"label":"Gateway Channel Max Restarts Per Hour","help":"Maximum number of health-monitor-initiated channel restarts allowed within a rolling one-hour window. Once hit, further restarts are skipped until the window expires. Default: 10.","hasChildren":false}
 {"recordType":"path","path":"gateway.channelStaleEventThresholdMinutes","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["network"],"label":"Gateway Channel Stale Event Threshold (min)","help":"How many minutes a connected channel can go without receiving any event before the health monitor treats it as a stale socket and triggers a restart. Default: 30.","hasChildren":false}
 {"recordType":"path","path":"gateway.controlUi","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["network"],"label":"Control UI","help":"Control UI hosting settings including enablement, pathing, and browser-origin/auth hardening behavior. Keep UI exposure minimal and pair with strong auth controls before internet-facing deployments.","hasChildren":true}
-{"recordType":"path","path":"gateway.controlUi.allowedOrigins","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access","network"],"label":"Control UI Allowed Origins","help":"Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com). Required for non-loopback Control UI deployments unless dangerous Host-header fallback is explicitly enabled. Setting [\"*\"] means allow any browser origin and should be avoided outside tightly controlled local testing.","hasChildren":true}
+{"recordType":"path","path":"gateway.controlUi.allowedOrigins","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access","network"],"label":"Control UI Allowed Origins","help":"Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com). Required for non-loopback Control UI deployments unless dangerous Host-header fallback is explicitly enabled.","hasChildren":true}
 {"recordType":"path","path":"gateway.controlUi.allowedOrigins.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"gateway.controlUi.allowInsecureAuth","kind":"core","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access","advanced","network","security"],"label":"Insecure Control UI Auth Toggle","help":"Loosens strict browser auth checks for Control UI when you must run a non-standard setup. Keep this off unless you trust your network and proxy path, because impersonation risk is higher.","hasChildren":false}
 {"recordType":"path","path":"gateway.controlUi.basePath","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["network","storage"],"label":"Control UI Base Path","help":"Optional URL prefix where the Control UI is served (e.g. /openclaw).","hasChildren":false}
@@ -3677,7 +3667,7 @@
 {"recordType":"path","path":"gateway.trustedProxies","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["network"],"label":"Gateway Trusted Proxy CIDRs","help":"CIDR/IP allowlist of upstream proxies permitted to provide forwarded client identity headers. Keep this list narrow so untrusted hops cannot impersonate users.","hasChildren":true}
 {"recordType":"path","path":"gateway.trustedProxies.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"hooks","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Hooks","help":"Inbound webhook automation surface for mapping external events into wake or agent actions in OpenClaw. Keep this locked down with explicit token/session/agent controls before exposing it beyond trusted networks.","hasChildren":true}
-{"recordType":"path","path":"hooks.allowedAgentIds","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Hooks Allowed Agent IDs","help":"Allowlist of agent IDs that hook mappings are allowed to target when selecting execution agents. Use this to constrain automation events to dedicated service agents and reduce blast radius if a hook token is exposed.","hasChildren":true}
+{"recordType":"path","path":"hooks.allowedAgentIds","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Hooks Allowed Agent IDs","help":"Allowlist of agent IDs that hook mappings are allowed to target when selecting execution agents. Use this to constrain automation events to dedicated service agents.","hasChildren":true}
 {"recordType":"path","path":"hooks.allowedAgentIds.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"hooks.allowedSessionKeyPrefixes","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access","storage"],"label":"Hooks Allowed Session Key Prefixes","help":"Allowlist of accepted session-key prefixes for inbound hook requests when caller-provided keys are enabled. Use narrow prefixes to prevent arbitrary session-key injection.","hasChildren":true}
 {"recordType":"path","path":"hooks.allowedSessionKeyPrefixes.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
@@ -3764,7 +3754,7 @@
 {"recordType":"path","path":"hooks.path","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Hooks Endpoint Path","help":"HTTP path used by the hooks endpoint (for example `/hooks`) on the gateway control server. Use a non-guessable path and combine it with token validation for defense in depth.","hasChildren":false}
 {"recordType":"path","path":"hooks.presets","kind":"core","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Hooks Presets","help":"Named hook preset bundles applied at load time to seed standard mappings and behavior defaults. Keep preset usage explicit so operators can audit which automations are active.","hasChildren":true}
 {"recordType":"path","path":"hooks.presets.*","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"hooks.token","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":true,"tags":["auth","security"],"label":"Hooks Auth Token","help":"Shared bearer token checked by hooks ingress for request authentication before mappings run. Treat holders as full-trust callers for the hook ingress surface, not as a separate non-owner role. Use environment substitution and rotate regularly when webhook endpoints are internet-accessible.","hasChildren":false}
+{"recordType":"path","path":"hooks.token","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":true,"tags":["auth","security"],"label":"Hooks Auth Token","help":"Shared bearer token checked by hooks ingress for request authentication before mappings run. Use environment substitution and rotate regularly when webhook endpoints are internet-accessible.","hasChildren":false}
 {"recordType":"path","path":"hooks.transformsDir","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Hooks Transforms Directory","help":"Base directory for hook transform modules referenced by mapping transform.module paths. Use a controlled repo directory so dynamic imports remain reviewable and predictable.","hasChildren":false}
 {"recordType":"path","path":"logging","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Logging","help":"Logging behavior controls for severity, output destinations, formatting, and sensitive-data redaction. Keep levels and redaction strict enough for production while preserving useful diagnostics.","hasChildren":true}
 {"recordType":"path","path":"logging.consoleLevel","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["observability"],"label":"Console Log Level","help":"Console-specific log threshold: \"silent\", \"fatal\", \"error\", \"warn\", \"info\", \"debug\", or \"trace\" for terminal output control. Use this to keep local console quieter while retaining richer file logging if needed.","hasChildren":false}
@@ -4103,15 +4093,6 @@
 {"recordType":"path","path":"plugins.entries.byteplus.subagent.allowedModels","kind":"plugin","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Plugin Subagent Allowed Models","help":"Allowed override targets for trusted plugin subagent runs as canonical \"provider/model\" refs. Use \"*\" only when you intentionally allow any model.","hasChildren":true}
 {"recordType":"path","path":"plugins.entries.byteplus.subagent.allowedModels.*","kind":"plugin","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"plugins.entries.byteplus.subagent.allowModelOverride","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Plugin Subagent Model Override","help":"Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.","hasChildren":false}
-{"recordType":"path","path":"plugins.entries.chutes","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/chutes-provider","help":"OpenClaw Chutes.ai provider plugin (plugin: chutes)","hasChildren":true}
-{"recordType":"path","path":"plugins.entries.chutes.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/chutes-provider Config","help":"Plugin-defined config payload for chutes.","hasChildren":false}
-{"recordType":"path","path":"plugins.entries.chutes.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/chutes-provider","hasChildren":false}
-{"recordType":"path","path":"plugins.entries.chutes.hooks","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Hook Policy","help":"Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.","hasChildren":true}
-{"recordType":"path","path":"plugins.entries.chutes.hooks.allowPromptInjection","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Prompt Injection Hooks","help":"Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.","hasChildren":false}
-{"recordType":"path","path":"plugins.entries.chutes.subagent","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Plugin Subagent Policy","help":"Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.","hasChildren":true}
-{"recordType":"path","path":"plugins.entries.chutes.subagent.allowedModels","kind":"plugin","type":"array","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Plugin Subagent Allowed Models","help":"Allowed override targets for trusted plugin subagent runs as canonical \"provider/model\" refs. Use \"*\" only when you intentionally allow any model.","hasChildren":true}
-{"recordType":"path","path":"plugins.entries.chutes.subagent.allowedModels.*","kind":"plugin","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
-{"recordType":"path","path":"plugins.entries.chutes.subagent.allowModelOverride","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["access"],"label":"Allow Plugin Subagent Model Override","help":"Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.","hasChildren":false}
 {"recordType":"path","path":"plugins.entries.cloudflare-ai-gateway","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/cloudflare-ai-gateway-provider","help":"OpenClaw Cloudflare AI Gateway provider plugin (plugin: cloudflare-ai-gateway)","hasChildren":true}
 {"recordType":"path","path":"plugins.entries.cloudflare-ai-gateway.config","kind":"plugin","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"@openclaw/cloudflare-ai-gateway-provider Config","help":"Plugin-defined config payload for cloudflare-ai-gateway.","hasChildren":false}
 {"recordType":"path","path":"plugins.entries.cloudflare-ai-gateway.enabled","kind":"plugin","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Enable @openclaw/cloudflare-ai-gateway-provider","hasChildren":false}

docs/cli/acp.md

@@ -8,7 +8,7 @@ title: "acp"
 
 # acp
 
-Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an OpenClaw Gateway.
+Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to a OpenClaw Gateway.
 
 This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
 over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
@@ -102,7 +102,7 @@ Permission model (client debug mode):
 ## How to use this
 
 Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
-it to drive an OpenClaw Gateway session.
+it to drive a OpenClaw Gateway session.
 
 1. Ensure the Gateway is running (local or remote).
 2. Configure the Gateway target (config or flags).

docs/cli/index.md

@@ -276,9 +276,9 @@ Note: plugins can add additional top-level commands (for example `openclaw voice
 ## Secrets
 
 - `openclaw secrets reload` — re-resolve refs and atomically swap the runtime snapshot.
-- `openclaw secrets audit` — scan for plaintext residues, unresolved refs, and precedence drift (`--allow-exec` to execute exec providers during audit).
-- `openclaw secrets configure` — interactive helper for provider setup + SecretRef mapping + preflight/apply (`--allow-exec` to execute exec providers during preflight and exec-containing apply flows).
-- `openclaw secrets apply --from <plan.json>` — apply a previously generated plan (`--dry-run` supported; use `--allow-exec` to permit exec providers in dry-run and exec-containing write plans).
+- `openclaw secrets audit` — scan for plaintext residues, unresolved refs, and precedence drift.
+- `openclaw secrets configure` — interactive helper for provider setup + SecretRef mapping + preflight/apply.
+- `openclaw secrets apply --from <plan.json>` — apply a previously generated plan (`--dry-run` supported).
 
 ## Plugins
 

docs/cli/plugins.md

@@ -21,7 +21,6 @@ Related:
 
 ```bash
 openclaw plugins list
-openclaw plugins install <path-or-spec>
 openclaw plugins inspect <id>
 openclaw plugins enable <id>
 openclaw plugins disable <id>
@@ -32,6 +31,8 @@ openclaw plugins update --all
 openclaw plugins marketplace list <marketplace>
 ```
 
+`info` is an alias for `inspect`.
+
 Bundled plugins ship with OpenClaw but start disabled. Use `plugins enable` to
 activate them.
 
@@ -158,18 +159,16 @@ openclaw plugins inspect <id> --json
 ```
 
 Deep introspection for a single plugin. Shows identity, load status, source,
-registered capabilities, hooks, tools, commands, services, gateway methods,
-HTTP routes, policy flags, diagnostics, and install metadata.
+plugin shape, registered capabilities, hooks, tools, commands, services,
+gateway methods, HTTP routes, policy flags, diagnostics, and install metadata.
 
-Each plugin is classified by what it actually registers at runtime:
+Plugin shape is derived from actual registration behavior:
 
-- **plain-capability** — one capability type (e.g. a provider-only plugin)
-- **hybrid-capability** — multiple capability types (e.g. text + speech + images)
+- **plain-capability** — one capability type registered
+- **hybrid-capability** — multiple capability types registered
 - **hook-only** — only hooks, no capabilities or surfaces
 - **non-capability** — tools/commands/services but no capabilities
 
-See [Plugins](/tools/plugin#plugin-shapes) for more on the capability model.
-
 The `--json` flag outputs a machine-readable report suitable for scripting and
 auditing.
 

docs/cli/secrets.md

@@ -14,9 +14,9 @@ Use `openclaw secrets` to manage SecretRefs and keep the active runtime snapshot
 Command roles:
 
 - `reload`: gateway RPC (`secrets.reload`) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
-- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless `--allow-exec` is set).
+- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift.
 - `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
-- `apply`: execute a saved plan (`--dry-run` for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless `--allow-exec` is set), then scrub targeted plaintext residues.
+- `apply`: execute a saved plan (`--dry-run` for validation only), then scrub targeted plaintext residues.
 
 Recommended operator loop:
 
@@ -29,8 +29,6 @@ openclaw secrets audit --check
 openclaw secrets reload
 ```
 
-If your plan includes `exec` SecretRefs/providers, pass `--allow-exec` on both dry-run and write apply commands.
-
 Exit code note for CI/gates:
 
 - `audit --check` returns `1` on findings.
@@ -75,7 +73,6 @@ Header residue note:
 openclaw secrets audit
 openclaw secrets audit --check
 openclaw secrets audit --json
-openclaw secrets audit --allow-exec
 ```
 
 Exit behavior:
@@ -86,7 +83,6 @@ Exit behavior:
 Report shape highlights:
 
 - `status`: `clean | findings | unresolved`
-- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
 - `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
 - finding codes:
   - `PLAINTEXT_FOUND`
@@ -119,7 +115,6 @@ Flags:
 - `--providers-only`: configure `secrets.providers` only, skip credential mapping.
 - `--skip-provider-setup`: skip provider setup and map credentials to existing providers.
 - `--agent <id>`: scope `auth-profiles.json` target discovery and writes to one agent store.
-- `--allow-exec`: allow exec SecretRef checks during preflight/apply (may execute provider commands).
 
 Notes:
 
@@ -129,7 +124,6 @@ Notes:
 - `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
 - Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
 - It performs preflight resolution before apply.
-- If preflight/apply includes exec refs, keep `--allow-exec` set for both steps.
 - Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
 - Apply path is one-way for scrubbed plaintext values.
 - Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
@@ -147,19 +141,10 @@ Apply or preflight a plan generated previously:
 
 ```bash
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
 ```
 
-Exec behavior:
-
-- `--dry-run` validates preflight without writing files.
-- exec SecretRef checks are skipped by default in dry-run.
-- write mode rejects plans that contain exec SecretRefs/providers unless `--allow-exec` is set.
-- Use `--allow-exec` to opt in to exec provider checks/execution in either mode.
-
 Plan contract details (allowed target paths, validation rules, and failure semantics):
 
 - [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)

docs/docs.json

@@ -1055,7 +1055,6 @@
                   "plugins/zalouser",
                   "plugins/manifest",
                   "plugins/agent-tools",
-                  "tools/capability-cookbook",
                   "prose"
                 ]
               },

docs/gateway/secrets-plan-contract.md

@@ -81,12 +81,6 @@ Invalid plan target path for models.providers.apiKey: models.providers.openai.ba
 
 No writes are committed for an invalid plan.
 
-## Exec provider consent behavior
-
-- `--dry-run` skips exec SecretRef checks by default.
-- Plans containing exec SecretRefs/providers are rejected in write mode unless `--allow-exec` is set.
-- When validating/applying exec-containing plans, pass `--allow-exec` in both dry-run and write commands.
-
 ## Runtime and audit scope notes
 
 - Ref-only `auth-profiles.json` entries (`keyRef`/`tokenRef`) are included in runtime resolution and audit coverage.
@@ -100,10 +94,6 @@ openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
 
 # Then apply for real
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
-
-# For exec-containing plans, opt in explicitly in both modes
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
 ```
 
 If apply fails with an invalid target path message, regenerate the plan with `openclaw secrets configure` or fix the target path to a supported shape above.

docs/gateway/secrets.md

@@ -414,11 +414,6 @@ Findings include:
 - precedence shadowing (`auth-profiles.json` taking priority over `openclaw.json` refs)
 - legacy residues (`auth.json`, OAuth reminders)
 
-Exec note:
-
-- By default, audit skips exec SecretRef resolvability checks to avoid command side effects.
-- Use `openclaw secrets audit --allow-exec` to execute exec providers during audit.
-
 Header residue note:
 
 - Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
@@ -434,11 +429,6 @@ Interactive helper that:
 - runs preflight resolution
 - can apply immediately
 
-Exec note:
-
-- Preflight skips exec SecretRef checks unless `--allow-exec` is set.
-- If you apply directly from `configure --apply` and the plan includes exec refs/providers, keep `--allow-exec` set for the apply step too.
-
 Helpful modes:
 
 - `openclaw secrets configure --providers-only`
@@ -457,16 +447,9 @@ Apply a saved plan:
 
 ```bash
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
 openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
-openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
 ```
 
-Exec note:
-
-- dry-run skips exec checks unless `--allow-exec` is set.
-- write mode rejects plans containing exec SecretRefs/providers unless `--allow-exec` is set.
-
 For strict target/path contract details and exact rejection rules, see:
 
 - [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)

docs/install/migrating.md

@@ -1,5 +1,5 @@
 ---
-summary: "Move (migrate) an OpenClaw install from one machine to another"
+summary: "Move (migrate) a OpenClaw install from one machine to another"
 read_when:
   - You are moving OpenClaw to a new laptop/server
   - You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
@@ -8,7 +8,7 @@ title: "Migration Guide"
 
 # Migrating OpenClaw to a new machine
 
-This guide migrates an OpenClaw Gateway from one machine to another **without redoing onboarding**.
+This guide migrates a OpenClaw Gateway from one machine to another **without redoing onboarding**.
 
 The migration is simple conceptually:
 

docs/pi.md

@@ -119,24 +119,19 @@ src/agents/
 │   ├── browser-tool.ts
 │   ├── canvas-tool.ts
 │   ├── cron-tool.ts
+│   ├── discord-actions*.ts
 │   ├── gateway-tool.ts
 │   ├── image-tool.ts
 │   ├── message-tool.ts
 │   ├── nodes-tool.ts
 │   ├── session*.ts
+│   ├── slack-actions.ts
+│   ├── telegram-actions.ts
 │   ├── web-*.ts
-│   └── ...
+│   └── whatsapp-actions.ts
 └── ...
 ```
 
-Channel-specific message action runtimes now live in the plugin-owned extension
-directories instead of under `src/agents/tools`, for example:
-
-- `extensions/discord/src/actions/runtime*.ts`
-- `extensions/slack/src/action-runtime.ts`
-- `extensions/telegram/src/action-runtime.ts`
-- `extensions/whatsapp/src/action-runtime.ts`
-
 ## Core Integration Flow
 
 ### 1. Running an Embedded Agent

docs/platforms/mac/remote.md

@@ -7,7 +7,7 @@ title: "Remote Control"
 
 # Remote OpenClaw (macOS ⇄ remote host)
 
-This flow lets the macOS app act as a full remote control for an OpenClaw gateway running on another host (desktop/server). It’s the app’s **Remote over SSH** (remote run) feature. All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from _Settings → General_.
+This flow lets the macOS app act as a full remote control for a OpenClaw gateway running on another host (desktop/server). It’s the app’s **Remote over SSH** (remote run) feature. All features—health checks, Voice Wake forwarding, and Web Chat—reuse the same remote SSH configuration from _Settings → General_.
 
 ## Modes
 

docs/plugins/manifest.md

@@ -1,7 +1,7 @@
 ---
 summary: "Plugin manifest + JSON schema requirements (strict config validation)"
 read_when:
-  - You are building an OpenClaw plugin
+  - You are building a OpenClaw plugin
   - You need to ship a plugin config schema or debug plugin validation errors
 title: "Plugin Manifest"
 ---
@@ -32,8 +32,7 @@ Every native OpenClaw plugin **must** ship a `openclaw.plugin.json` file in the
 plugin errors and block config validation.
 
 See the full plugin system guide: [Plugins](/tools/plugin).
-For the native capability model and current external-compatibility guidance:
-[Capability model](/tools/plugin#public-capability-model).
+For the public capability model: [Capability model](/tools/plugin#public-capability-model).
 
 ## Required fields
 
@@ -121,8 +120,6 @@ Example:
 - If plugin config exists but the plugin is **disabled**, the config is kept and
   a **warning** is surfaced in Doctor + logs.
 
-See [Configuration reference](/configuration) for the full `plugins.*` schema.
-
 ## Notes
 
 - The manifest is **required for native OpenClaw plugins**, including local filesystem loads.
@@ -133,9 +130,7 @@ See [Configuration reference](/configuration) for the full `plugins.*` schema.
   runtime just to inspect env names.
 - `providerAuthChoices` is the cheap metadata path for auth-choice pickers,
   `--auth-choice` resolution, preferred-provider mapping, and simple onboarding
-  CLI flag registration before provider runtime loads. For runtime wizard
-  metadata that requires provider code, see
-  [Provider runtime hooks](/tools/plugin#provider-runtime-hooks).
+  CLI flag registration before provider runtime loads.
 - Exclusive plugin kinds are selected through `plugins.slots.*`.
   - `kind: "memory"` is selected by `plugins.slots.memory`.
   - `kind: "context-engine"` is selected by `plugins.slots.contextEngine`

docs/providers/index.md

@@ -47,7 +47,6 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugi
 - [Vercel AI Gateway](/providers/vercel-ai-gateway)
 - [Venice (Venice AI, privacy-focused)](/providers/venice)
 - [vLLM (local models)](/providers/vllm)
-- [xAI](/providers/xai)
 - [Xiaomi](/providers/xiaomi)
 - [Z.AI](/providers/zai)
 

docs/providers/models.md

@@ -39,7 +39,6 @@ model as `provider/model`.
 - [Venice (Venice AI)](/providers/venice)
 - [Amazon Bedrock](/providers/bedrock)
 - [Qianfan](/providers/qianfan)
-- [xAI](/providers/xai)
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
 see [Model providers](/concepts/model-providers).

docs/providers/xai.md

@@ -1,61 +0,0 @@
----
-summary: "Use xAI Grok models in OpenClaw"
-read_when:
-  - You want to use Grok models in OpenClaw
-  - You are configuring xAI auth or model ids
-title: "xAI"
----
-
-# xAI
-
-OpenClaw ships a bundled `xai` provider plugin for Grok models.
-
-## Setup
-
-1. Create an API key in the xAI console.
-2. Set `XAI_API_KEY`, or run:
-
-```bash
-openclaw onboard --auth-choice xai-api-key
-```
-
-3. Pick a model such as:
-
-```json5
-{
-  agents: { defaults: { model: { primary: "xai/grok-4" } } },
-}
-```
-
-## Current bundled model catalog
-
-OpenClaw now includes these xAI model families out of the box:
-
-- `grok-4`, `grok-4-0709`
-- `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`
-- `grok-4-1-fast-reasoning`, `grok-4-1-fast-non-reasoning`
-- `grok-4.20-experimental-beta-0304-reasoning`
-- `grok-4.20-experimental-beta-0304-non-reasoning`
-- `grok-code-fast-1`
-
-The plugin also forward-resolves newer `grok-4*` and `grok-code-fast*` ids when
-they follow the same API shape.
-
-## Web search
-
-The bundled `grok` web-search provider uses `XAI_API_KEY` too:
-
-```bash
-openclaw config set tools.web.search.provider grok
-```
-
-## Known limits
-
-- Auth is API-key only today. There is no xAI OAuth/device-code flow in OpenClaw yet.
-- `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard OpenClaw xAI transport.
-- Native xAI server-side tools such as `x_search` and `code_execution` are not yet first-class model-provider features in the bundled plugin.
-
-## Notes
-
-- OpenClaw applies xAI-specific tool-schema and tool-call compatibility fixes automatically on the shared runner path.
-- For the broader provider overview, see [Model providers](/providers/index).

docs/start/showcase.md

@@ -231,7 +231,7 @@ Triggered by a roof camera: ask OpenClaw to snap a sky photo whenever it looks p
 <Card title="Visual Morning Briefing Scene" icon="robot" href="https://x.com/buddyhadry/status/2010005331925954739">
   **@buddyhadry** • `automation` `briefing` `images` `telegram`
 
-A scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/quote) via an OpenClaw persona.
+A scheduled prompt generates a single "scene" image each morning (weather, tasks, date, favorite post/quote) via a OpenClaw persona.
 </Card>
 
 <Card title="Padel Court Booking" icon="calendar-check" href="https://github.com/joshp123/padel-cli">

docs/tools/browser.md

@@ -191,7 +191,7 @@ Notes:
 ## Browserless (hosted remote CDP)
 
 [Browserless](https://browserless.io) is a hosted Chromium service that exposes
-CDP endpoints over HTTPS. You can point an OpenClaw browser profile at a
+CDP endpoints over HTTPS. You can point a OpenClaw browser profile at a
 Browserless region endpoint and authenticate with your API key.
 
 Example:

docs/tools/clawhub.md

@@ -66,7 +66,7 @@ pnpm add -g clawhub
 
 ## How it fits into OpenClaw
 
-By default, the CLI installs skills into `./skills` under your current working directory. If an OpenClaw workspace is configured, `clawhub` falls back to that workspace unless you override `--workdir` (or `CLAWHUB_WORKDIR`). OpenClaw loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.openclaw/skills` or bundled skills, workspace skills take precedence.
+By default, the CLI installs skills into `./skills` under your current working directory. If a OpenClaw workspace is configured, `clawhub` falls back to that workspace unless you override `--workdir` (or `CLAWHUB_WORKDIR`). OpenClaw loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.openclaw/skills` or bundled skills, workspace skills take precedence.
 
 For more detail on how skills are loaded, shared, and gated, see
 [Skills](/tools/skills).

docs/tools/plugin.md

@@ -37,8 +37,12 @@ openclaw plugins list
 openclaw plugins install @openclaw/voice-call
 ```
 
-Npm specs are registry-only. See [install rules](/cli/plugins#install) for
-details on pinning, prerelease gating, and supported spec formats.
+Npm specs are **registry-only** (package name + optional **exact version** or
+**dist-tag**). Git/URL/file specs and semver ranges are rejected.
+
+Bare specs and `@latest` stay on the stable track. If npm resolves either of
+those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a
+prerelease tag such as `@beta`/`@rc` or an exact prerelease version.
 
 3. Restart the Gateway, then configure under `plugins.entries.<id>.config`.
 
@@ -103,8 +107,8 @@ conversation, and it runs after core approval handling finishes.
 
 ## Public capability model
 
-Capabilities are the public **native plugin** model inside OpenClaw. Every
-native OpenClaw plugin registers against one or more capability types:
+Capabilities are the public plugin model. Every native OpenClaw plugin
+registers against one or more capability types:
 
 | Capability          | Registration method                           | Example plugins           |
 | ------------------- | --------------------------------------------- | ------------------------- |
@@ -116,31 +120,7 @@ native OpenClaw plugin registers against one or more capability types:
 | Channel / messaging | `api.registerChannel(...)`                    | `msteams`, `matrix`       |
 
 A plugin that registers zero capabilities but provides hooks, tools, or
-services is a **legacy hook-only** plugin. That pattern is still fully supported.
-
-### External compatibility stance
-
-The capability model is landed in core and used by bundled/native plugins
-today, but external plugin compatibility still needs a tighter bar than "it is
-exported, therefore it is frozen."
-
-Current guidance:
-
-- **existing external plugins:** keep hook-based integrations working; treat
-  this as the compatibility baseline
-- **new bundled/native plugins:** prefer explicit capability registration over
-  vendor-specific reach-ins or new hook-only designs
-- **external plugins adopting capability registration:** allowed, but treat the
-  capability-specific helper surfaces as evolving unless docs explicitly mark a
-  contract as stable
-
-Practical rule:
-
-- capability registration APIs are the intended direction
-- legacy hooks remain the safest no-breakage path for external plugins during
-  the transition
-- exported helper subpaths are not all equal; prefer the narrow documented
-  contract, not incidental helper exports
+services is a **legacy hook-only** plugin. That shape is still fully supported.
 
 ### Plugin shapes
 
@@ -160,6 +140,13 @@ registration behavior (not just static metadata):
 Use `openclaw plugins inspect <id>` to see a plugin's shape and capability
 breakdown. See [CLI reference](/cli/plugins#inspect) for details.
 
+### Capability labels
+
+Plugin capabilities use two stability labels:
+
+- `public` — stable, documented, and safe to depend on
+- `experimental` — may change between releases
+
 ### Legacy hooks
 
 The `before_agent_start` hook remains supported as a compatibility path for
@@ -215,7 +202,7 @@ The current boundary is:
   channel-specific schema fragments
 - channel plugins execute the final action through their action adapter
 
-For channel plugins, the SDK surface is
+For channel plugins, the preferred SDK surface is
 `ChannelMessageActionAdapter.describeMessageTool(...)`. That unified discovery
 call lets a plugin return its visible actions, capabilities, and schema
 contributions together so those pieces do not drift apart.
@@ -241,26 +228,6 @@ responsible for forwarding the current chat/session identity into the plugin
 discovery boundary so the shared `message` tool exposes the right channel-owned
 surface for the current turn.
 
-For channel-owned execution helpers, bundled plugins should keep the execution
-runtime inside their own extension modules. Core no longer owns the Discord,
-Slack, Telegram, or WhatsApp message-action runtimes under `src/agents/tools`.
-We do not publish separate `plugin-sdk/*-action-runtime` subpaths, and bundled
-plugins should import their own local runtime code directly from their
-extension-owned modules.
-
-For polls specifically, there are two execution paths:
-
-- `outbound.sendPoll` is the shared baseline for channels that fit the common
-  poll model
-- `actions.handleAction("poll")` is the preferred path for channel-specific
-  poll semantics or extra poll parameters
-
-Core now defers shared poll parsing until after plugin poll dispatch declines
-the action, so plugin-owned poll handlers can accept channel-specific poll
-fields without being blocked by the generic poll parser first.
-
-See [Load pipeline](#load-pipeline) for the full startup sequence.
-
 ## Capability ownership model
 
 OpenClaw treats a native plugin as the ownership boundary for a **company** or a
@@ -440,7 +407,7 @@ native OpenClaw plugin sources. OpenClaw resolves the marketplace entry first,
 then runs the normal install path for the resolved source.
 
 They are shown in the plugin list as `format=bundle`, with a subtype of
-`codex`, `claude`, or `cursor` in verbose/inspect output.
+`codex` or `claude` in verbose/info output.
 
 See [Plugin bundles](/plugins/bundles) for the exact detection rules, mapping
 behavior, and current support matrix.
@@ -570,8 +537,7 @@ Native OpenClaw plugins can register capabilities and surfaces:
 - **Skills** (by listing `skills` directories in the plugin manifest)
 - **Auto-reply commands** (execute without invoking the AI agent)
 
-Native OpenClaw plugins run in-process with the Gateway (see
-[Execution model](#execution-model) for trust implications).
+Native OpenClaw plugins run **in‑process** with the Gateway, so treat them as trusted code.
 Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).
 
 Think of these registrations as **capability claims**. A plugin is not supposed
@@ -696,35 +662,112 @@ one-flag auth wiring without loading provider runtime. Keep provider runtime
 `envVars` for operator-facing hints such as onboarding labels or OAuth
 client-id/client-secret setup vars.
 
-### Hook order and usage
+### Hook order
 
-For model/provider plugins, OpenClaw calls hooks in this rough order.
-The "When to use" column is the quick decision guide.
+For model/provider plugins, OpenClaw uses hooks in this rough order:
 
-| #   | Hook                          | What it does                                                                             | When to use                                                                          |
-| --- | ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| 1   | `catalog`                     | Publish provider config into `models.providers` during `models.json` generation          | Provider owns a catalog or base URL defaults                                         |
-| —   | _(built-in model lookup)_     | OpenClaw tries the normal registry/catalog path first                                    | _(not a plugin hook)_                                                                |
-| 2   | `resolveDynamicModel`         | Sync fallback for provider-owned model ids not in the local registry yet                 | Provider accepts arbitrary upstream model ids                                        |
-| 3   | `prepareDynamicModel`         | Async warm-up, then `resolveDynamicModel` runs again                                     | Provider needs network metadata before resolving unknown ids                         |
-| 4   | `normalizeResolvedModel`      | Final rewrite before the embedded runner uses the resolved model                         | Provider needs transport rewrites but still uses a core transport                    |
-| 5   | `capabilities`                | Provider-owned transcript/tooling metadata used by shared core logic                     | Provider needs transcript/provider-family quirks                                     |
-| 6   | `prepareExtraParams`          | Request-param normalization before generic stream option wrappers                        | Provider needs default request params or per-provider param cleanup                  |
-| 7   | `wrapStreamFn`                | Stream wrapper after generic wrappers are applied                                        | Provider needs request headers/body/model compat wrappers without a custom transport |
-| 8   | `formatApiKey`                | Auth-profile formatter: stored profile becomes the runtime `apiKey` string               | Provider stores extra auth metadata and needs a custom runtime token shape           |
-| 9   | `refreshOAuth`                | OAuth refresh override for custom refresh endpoints or refresh-failure policy            | Provider does not fit the shared `pi-ai` refreshers                                  |
-| 10  | `buildAuthDoctorHint`         | Repair hint appended when OAuth refresh fails                                            | Provider needs provider-owned auth repair guidance after refresh failure             |
-| 11  | `isCacheTtlEligible`          | Prompt-cache policy for proxy/backhaul providers                                         | Provider needs proxy-specific cache TTL gating                                       |
-| 12  | `buildMissingAuthMessage`     | Replacement for the generic missing-auth recovery message                                | Provider needs a provider-specific missing-auth recovery hint                        |
-| 13  | `suppressBuiltInModel`        | Stale upstream model suppression plus optional user-facing error hint                    | Provider needs to hide stale upstream rows or replace them with a vendor hint        |
-| 14  | `augmentModelCatalog`         | Synthetic/final catalog rows appended after discovery                                    | Provider needs synthetic forward-compat rows in `models list` and pickers            |
-| 15  | `isBinaryThinking`            | On/off reasoning toggle for binary-thinking providers                                    | Provider exposes only binary thinking on/off                                         |
-| 16  | `supportsXHighThinking`       | `xhigh` reasoning support for selected models                                            | Provider wants `xhigh` on only a subset of models                                    |
-| 17  | `resolveDefaultThinkingLevel` | Default `/think` level for a specific model family                                       | Provider owns default `/think` policy for a model family                             |
-| 18  | `isModernModelRef`            | Modern-model matcher for live profile filters and smoke selection                        | Provider owns live/smoke preferred-model matching                                    |
-| 19  | `prepareRuntimeAuth`          | Exchange a configured credential into the actual runtime token/key just before inference | Provider needs a token exchange or short-lived request credential                    |
-| 20  | `resolveUsageAuth`            | Resolve usage/billing credentials for `/usage` and related status surfaces               | Provider needs custom usage/quota token parsing or a different usage credential      |
-| 21  | `fetchUsageSnapshot`          | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved       | Provider needs a provider-specific usage endpoint or payload parser                  |
+1. `catalog`
+   Publish provider config into `models.providers` during `models.json`
+   generation.
+2. built-in/discovered model lookup
+   OpenClaw tries the normal registry/catalog path first.
+3. `resolveDynamicModel`
+   Sync fallback for provider-owned model ids that are not in the local
+   registry yet.
+4. `prepareDynamicModel`
+   Async warm-up only on async model resolution paths, then
+   `resolveDynamicModel` runs again.
+5. `normalizeResolvedModel`
+   Final rewrite before the embedded runner uses the resolved model.
+6. `capabilities`
+   Provider-owned transcript/tooling metadata used by shared core logic.
+7. `prepareExtraParams`
+   Provider-owned request-param normalization before generic stream option wrappers.
+8. `wrapStreamFn`
+   Provider-owned stream wrapper after generic wrappers are applied.
+9. `formatApiKey`
+   Provider-owned auth-profile formatter used when a stored auth profile needs
+   to become the runtime `apiKey` string.
+10. `refreshOAuth`
+    Provider-owned OAuth refresh override for custom refresh endpoints or
+    refresh-failure policy.
+11. `buildAuthDoctorHint`
+    Provider-owned repair hint appended when OAuth refresh fails.
+12. `isCacheTtlEligible`
+    Provider-owned prompt-cache policy for proxy/backhaul providers.
+13. `buildMissingAuthMessage`
+    Provider-owned replacement for the generic missing-auth recovery message.
+14. `suppressBuiltInModel`
+    Provider-owned stale upstream model suppression plus optional user-facing
+    error hint.
+15. `augmentModelCatalog`
+    Provider-owned synthetic/final catalog rows appended after discovery.
+16. `isBinaryThinking`
+    Provider-owned on/off reasoning toggle for binary-thinking providers.
+17. `supportsXHighThinking`
+    Provider-owned `xhigh` reasoning support for selected models.
+18. `resolveDefaultThinkingLevel`
+    Provider-owned default `/think` level for a specific model family.
+19. `isModernModelRef`
+    Provider-owned modern-model matcher used by live profile filters and smoke
+    selection.
+20. `prepareRuntimeAuth`
+    Exchanges a configured credential into the actual runtime token/key just
+    before inference.
+21. `resolveUsageAuth`
+    Resolves usage/billing credentials for `/usage` and related status
+    surfaces.
+22. `fetchUsageSnapshot`
+    Fetches and normalizes provider-specific usage/quota snapshots after auth
+    is resolved.
+
+### Which hook to use
+
+- `catalog`: publish provider config and model catalogs into `models.providers`
+- `resolveDynamicModel`: handle pass-through or forward-compat model ids that are not in the local registry yet
+- `prepareDynamicModel`: async warm-up before retrying dynamic resolution (for example refresh provider metadata cache)
+- `normalizeResolvedModel`: rewrite a resolved model's transport/base URL/compat before inference
+- `capabilities`: publish provider-family and transcript/tooling quirks without hardcoding provider ids in core
+- `prepareExtraParams`: set provider defaults or normalize provider-specific per-model params before generic stream wrapping
+- `wrapStreamFn`: add provider-specific headers/payload/model compat patches while still using the normal `pi-ai` execution path
+- `formatApiKey`: turn a stored auth profile into the runtime `apiKey` string without hardcoding provider token blobs in core
+- `refreshOAuth`: own OAuth refresh for providers that do not fit the shared `pi-ai` refreshers
+- `buildAuthDoctorHint`: append provider-owned auth repair guidance when refresh fails
+- `isCacheTtlEligible`: decide whether provider/model pairs should use cache TTL metadata
+- `buildMissingAuthMessage`: replace the generic auth-store error with a provider-specific recovery hint
+- `suppressBuiltInModel`: hide stale upstream rows and optionally return a provider-owned error for direct resolution failures
+- `augmentModelCatalog`: append synthetic/final catalog rows after discovery and config merging
+- `isBinaryThinking`: expose binary on/off reasoning UX without hardcoding provider ids in `/think`
+- `supportsXHighThinking`: opt specific models into the `xhigh` reasoning level
+- `resolveDefaultThinkingLevel`: keep provider/model default reasoning policy out of core
+- `isModernModelRef`: keep live/smoke model family inclusion rules with the provider
+- `prepareRuntimeAuth`: exchange a configured credential into the actual short-lived runtime token/key used for requests
+- `resolveUsageAuth`: resolve provider-owned credentials for usage/billing endpoints without hardcoding token parsing in core
+- `fetchUsageSnapshot`: own provider-specific usage endpoint fetch/parsing while core keeps summary fan-out and formatting
+
+Rule of thumb:
+
+- provider owns a catalog or base URL defaults: use `catalog`
+- provider accepts arbitrary upstream model ids: use `resolveDynamicModel`
+- provider needs network metadata before resolving unknown ids: add `prepareDynamicModel`
+- provider needs transport rewrites but still uses a core transport: use `normalizeResolvedModel`
+- provider needs transcript/provider-family quirks: use `capabilities`
+- provider needs default request params or per-provider param cleanup: use `prepareExtraParams`
+- provider needs request headers/body/model compat wrappers without a custom transport: use `wrapStreamFn`
+- provider stores extra metadata in auth profiles and needs a custom runtime token shape: use `formatApiKey`
+- provider needs a custom OAuth refresh endpoint or refresh failure policy: use `refreshOAuth`
+- provider needs provider-owned auth repair guidance after refresh failure: use `buildAuthDoctorHint`
+- provider needs proxy-specific cache TTL gating: use `isCacheTtlEligible`
+- provider needs a provider-specific missing-auth recovery hint: use `buildMissingAuthMessage`
+- provider needs to hide stale upstream rows or replace them with a vendor hint: use `suppressBuiltInModel`
+- provider needs synthetic forward-compat rows in `models list` and pickers: use `augmentModelCatalog`
+- provider exposes only binary thinking on/off: use `isBinaryThinking`
+- provider wants `xhigh` on only a subset of models: use `supportsXHighThinking`
+- provider owns default `/think` policy for a model family: use `resolveDefaultThinkingLevel`
+- provider owns live/smoke preferred-model matching: use `isModernModelRef`
+- provider needs a token exchange or short-lived request credential: use `prepareRuntimeAuth`
+- provider needs custom usage/quota token parsing or a different usage credential: use `resolveUsageAuth`
+- provider needs a provider-specific usage endpoint or payload parser: use `fetchUsageSnapshot`
 
 If the provider needs a fully custom wire protocol or custom request executor,
 that is a different class of extension. These hooks are for provider behavior
@@ -1083,24 +1126,14 @@ Use SDK subpaths instead of the monolithic `openclaw/plugin-sdk` import when
 authoring plugins:
 
 - `openclaw/plugin-sdk/core` for the smallest generic plugin-facing contract.
-  It also carries small assembly helpers such as
-  `definePluginEntry`, `defineChannelPluginEntry`, `defineSetupPluginEntry`,
-  and `createChannelPluginBase` for bundled or third-party plugin entry wiring.
 - Domain subpaths such as `openclaw/plugin-sdk/channel-config-helpers`,
   `openclaw/plugin-sdk/channel-config-schema`,
   `openclaw/plugin-sdk/channel-policy`,
-  `openclaw/plugin-sdk/channel-runtime`,
-  `openclaw/plugin-sdk/config-runtime`,
-  `openclaw/plugin-sdk/agent-runtime`,
   `openclaw/plugin-sdk/lazy-runtime`,
   `openclaw/plugin-sdk/reply-history`,
   `openclaw/plugin-sdk/routing`,
   `openclaw/plugin-sdk/runtime-store`, and
   `openclaw/plugin-sdk/directory-runtime` for shared runtime/config helpers.
-- Narrow channel-core subpaths such as `openclaw/plugin-sdk/discord-core`,
-  `openclaw/plugin-sdk/telegram-core`, `openclaw/plugin-sdk/whatsapp-core`,
-  and `openclaw/plugin-sdk/line-core` for channel-specific primitives that
-  should stay smaller than the full channel helper barrels.
 - `openclaw/plugin-sdk/compat` remains as a legacy migration surface for older
   external plugins. Bundled plugins should not use it, and non-test imports emit
   a one-time deprecation warning outside test environments.
@@ -1140,54 +1173,6 @@ authoring plugins:
   `openclaw/plugin-sdk/twitch`, `openclaw/plugin-sdk/voice-call`,
   `openclaw/plugin-sdk/zalo`, and `openclaw/plugin-sdk/zalouser`.
 
-## Channel target resolution
-
-Channel plugins should own channel-specific target semantics. Keep the shared
-outbound host generic and use the messaging adapter surface for provider rules:
-
-- `messaging.inferTargetChatType({ to })` decides whether a normalized target
-  should be treated as `direct`, `group`, or `channel` before directory lookup.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` tells core whether an
-  input should skip straight to id-like resolution instead of directory search.
-- `messaging.targetResolver.resolveTarget(...)` is the plugin fallback when
-  core needs a final provider-owned resolution after normalization or after a
-  directory miss.
-- `messaging.resolveOutboundSessionRoute(...)` owns provider-specific session
-  route construction once a target is resolved.
-
-Recommended split:
-
-- Use `inferTargetChatType` for category decisions that should happen before
-  searching peers/groups.
-- Use `looksLikeId` for “treat this as an explicit/native target id” checks.
-- Use `resolveTarget` for provider-specific normalization fallback, not for
-  broad directory search.
-- Keep provider-native ids like chat ids, thread ids, JIDs, handles, and room
-  ids inside `target` values or provider-specific params, not in generic SDK
-  fields.
-
-## Config-backed directories
-
-Plugins that derive directory entries from config should keep that logic in the
-plugin and reuse the shared helpers from
-`openclaw/plugin-sdk/directory-runtime`.
-
-Use this when a channel needs config-backed peers/groups such as:
-
-- allowlist-driven DM peers
-- configured channel/group maps
-- account-scoped static directory fallbacks
-
-The shared helpers in `directory-runtime` only handle generic operations:
-
-- query filtering
-- limit application
-- deduping/normalization helpers
-- building `ChannelDirectoryEntry[]`
-
-Channel-specific account inspection and id normalization should stay in the
-plugin implementation.
-
 ## Provider catalogs
 
 Provider plugins can define model catalogs for inference with
@@ -1224,10 +1209,6 @@ Compatibility note:
 - New and migrated bundled plugins should use channel or extension-specific
   subpaths; use `core` plus explicit domain subpaths for generic surfaces, and
   treat `compat` as migration-only.
-- Capability-specific subpaths such as `image-generation`,
-  `media-understanding`, and `speech` exist because bundled/native plugins use
-  them today. Their presence does not by itself mean every exported helper is a
-  long-term frozen external contract.
 
 ## Read-only channel inspection
 
@@ -1351,7 +1332,6 @@ Compatible bundles may instead provide one of:
 
 - `.codex-plugin/plugin.json`
 - `.claude-plugin/plugin.json`
-- `.cursor-plugin/plugin.json`
 
 Bundle directories are discovered from the same roots as native plugins.
 
@@ -1556,8 +1536,7 @@ Fields:
 - `slots`: exclusive slot selectors such as `memory` and `contextEngine`
 - `entries.<id>`: per‑plugin toggles + config
 
-Config changes **require a gateway restart**. See
-[Configuration reference](/configuration) for the full config schema.
+Config changes **require a gateway restart**.
 
 Validation rules (strict):
 
@@ -1603,7 +1582,6 @@ Supported exclusive slots:
 
 If multiple plugins declare `kind: "memory"` or `kind: "context-engine"`, only
 the selected plugin loads for that slot. Others are disabled with diagnostics.
-Declare `kind` in your [plugin manifest](/plugins/manifest).
 
 ### Context engine plugins
 
@@ -1658,7 +1636,7 @@ openclaw plugins install ./extensions/voice-call # relative path ok
 openclaw plugins install ./plugin.tgz           # install from a local tarball
 openclaw plugins install ./plugin.zip           # install from a local zip
 openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev
-openclaw plugins install @openclaw/voice-call   # install from npm
+openclaw plugins install @openclaw/voice-call # install from npm
 openclaw plugins install @openclaw/voice-call --pin # store exact resolved name@version
 openclaw plugins update <id>
 openclaw plugins update --all
@@ -1667,11 +1645,14 @@ openclaw plugins disable <id>
 openclaw plugins doctor
 ```
 
-See [`openclaw plugins` CLI reference](/cli/plugins) for full details on each
-command (install rules, inspect output, marketplace installs, uninstall).
+`openclaw plugins list` shows the top-level format as `openclaw` or `bundle`.
+Verbose list/info output also shows bundle subtype (`codex` or `claude`) plus
+detected bundle capabilities.
 
-Plugins may also register their own top-level commands (example:
-`openclaw voicecall`).
+`plugins update` only works for npm installs tracked under `plugins.installs`.
+If stored integrity metadata changes between updates, OpenClaw warns and asks for confirmation (use global `--yes` to bypass prompts).
+
+Plugins may also register their own top‑level commands (example: `openclaw voicecall`).
 
 ## Plugin API (overview)
 
@@ -1729,8 +1710,7 @@ Recommended sequence:
    Add tests so ownership and registration shape stay explicit over time.
 
 This is how OpenClaw stays opinionated without becoming hardcoded to one
-provider's worldview. See the [Capability Cookbook](/tools/capability-cookbook)
-for a concrete file checklist and worked example.
+provider's worldview.
 
 ### Capability checklist
 
@@ -2479,7 +2459,7 @@ See [Voice Call](/plugins/voice-call) and `extensions/voice-call/README.md` for
 
 ## Safety notes
 
-Plugins run in-process with the Gateway (see [Execution model](#execution-model)):
+Plugins run in-process with the Gateway. Treat them as trusted code:
 
 - Only install plugins you trust.
 - Prefer `plugins.allow` allowlists.

docs/web/control-ui.md

@@ -242,7 +242,7 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
 Notes:
 
 - `gatewayUrl` is stored in localStorage after load and removed from the URL.
-- `token` should be passed via the URL fragment (`#token=...`) whenever possible. Fragments are not sent to the server, which avoids request-log and Referer leakage. Legacy `?token=` query params are still imported once for compatibility, but only as a fallback, and are stripped immediately after bootstrap.
+- `token` is preferably imported from the URL fragment, stored in sessionStorage for the current browser tab session and selected gateway URL, and stripped from the URL; legacy `?token=` query params are also imported once for compatibility and then removed.
 - `password` is kept in memory only.
 - When `gatewayUrl` is set, the UI does not fall back to config or environment credentials.
   Provide `token` (or `password`) explicitly. Missing explicit credentials is an error.

extensions/amazon-bedrock/index.test.ts

@@ -19,27 +19,4 @@ describe("amazon-bedrock provider plugin", () => {
       } as never),
     ).toBeUndefined();
   });
-
-  it("disables prompt caching for non-Anthropic Bedrock models", () => {
-    const provider = registerSingleProviderPlugin(amazonBedrockPlugin);
-    const wrapped = provider.wrapStreamFn?.({
-      provider: "amazon-bedrock",
-      modelId: "amazon.nova-micro-v1:0",
-      streamFn: (_model, _context, options) => options,
-    } as never);
-
-    expect(
-      wrapped?.(
-        {
-          api: "openai-completions",
-          provider: "amazon-bedrock",
-          id: "amazon.nova-micro-v1:0",
-        } as never,
-        { messages: [] } as never,
-        {},
-      ),
-    ).toMatchObject({
-      cacheRetention: "none",
-    });
-  });
 });

extensions/amazon-bedrock/index.ts

@@ -1,8 +1,4 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
-import {
-  createBedrockNoCacheWrapper,
-  isAnthropicBedrockModel,
-} from "openclaw/plugin-sdk/provider-stream";
 
 const PROVIDER_ID = "amazon-bedrock";
 const CLAUDE_46_MODEL_RE = /claude-(?:opus|sonnet)-4(?:\.|-)6(?:$|[-.])/i;
@@ -17,8 +13,6 @@ export default definePluginEntry({
       label: "Amazon Bedrock",
       docsPath: "/providers/models",
       auth: [],
-      wrapStreamFn: ({ modelId, streamFn }) =>
-        isAnthropicBedrockModel(modelId) ? streamFn : createBedrockNoCacheWrapper(streamFn),
       resolveDefaultThinkingLevel: ({ modelId }) =>
         CLAUDE_46_MODEL_RE.test(modelId.trim()) ? "adaptive" : undefined,
     });

extensions/bluebubbles/src/account-resolve.ts

@@ -1,5 +1,5 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 import { normalizeResolvedSecretInputString } from "./secret-input.js";
 
 export type BlueBubblesAccountResolveOpts = {

extensions/bluebubbles/src/accounts.ts

@@ -1,5 +1,5 @@
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import { createAccountListHelpers, type OpenClawConfig } from "./runtime-api.js";
+import { createAccountListHelpers, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { hasConfiguredSecretInput, normalizeSecretInputString } from "./secret-input.js";
 import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
 

extensions/bluebubbles/src/actions.test.ts

@@ -46,7 +46,7 @@ vi.mock("./probe.js", () => ({
 }));
 
 describe("bluebubblesMessageActions", () => {
-  const describeMessageTool = bluebubblesMessageActions.describeMessageTool!;
+  const listActions = bluebubblesMessageActions.listActions!;
   const supportsAction = bluebubblesMessageActions.supportsAction!;
   const extractToolSend = bluebubblesMessageActions.extractToolSend!;
   const handleAction = bluebubblesMessageActions.handleAction!;
@@ -74,12 +74,12 @@ describe("bluebubblesMessageActions", () => {
     vi.mocked(getCachedBlueBubblesPrivateApiStatus).mockReturnValue(null);
   });
 
-  describe("describeMessageTool", () => {
+  describe("listActions", () => {
     it("returns empty array when account is not enabled", () => {
       const cfg: OpenClawConfig = {
         channels: { bluebubbles: { enabled: false } },
       };
-      const actions = describeMessageTool({ cfg })?.actions ?? [];
+      const actions = listActions({ cfg });
       expect(actions).toEqual([]);
     });
 
@@ -87,7 +87,7 @@ describe("bluebubblesMessageActions", () => {
       const cfg: OpenClawConfig = {
         channels: { bluebubbles: { enabled: true } },
       };
-      const actions = describeMessageTool({ cfg })?.actions ?? [];
+      const actions = listActions({ cfg });
       expect(actions).toEqual([]);
     });
 
@@ -101,7 +101,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = describeMessageTool({ cfg })?.actions ?? [];
+      const actions = listActions({ cfg });
       expect(actions).toContain("react");
     });
 
@@ -116,7 +116,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = describeMessageTool({ cfg })?.actions ?? [];
+      const actions = listActions({ cfg });
       expect(actions).not.toContain("react");
       // Other actions should still be present
       expect(actions).toContain("edit");
@@ -134,7 +134,7 @@ describe("bluebubblesMessageActions", () => {
           },
         },
       };
-      const actions = describeMessageTool({ cfg })?.actions ?? [];
+      const actions = listActions({ cfg });
       expect(actions).toContain("sendAttachment");
       expect(actions).not.toContain("react");
       expect(actions).not.toContain("reply");

extensions/bluebubbles/src/actions.ts

@@ -1,6 +1,3 @@
-import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
-import { resolveBlueBubblesAccount } from "./accounts.js";
-import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe.js";
 import {
   BLUEBUBBLES_ACTION_NAMES,
   BLUEBUBBLES_ACTIONS,
@@ -13,7 +10,10 @@ import {
   readStringParam,
   type ChannelMessageActionAdapter,
   type ChannelMessageActionName,
-} from "./runtime-api.js";
+} from "openclaw/plugin-sdk/bluebubbles";
+import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe.js";
 import { normalizeSecretInputString } from "./secret-input.js";
 import {
   normalizeBlueBubblesHandle,
@@ -67,10 +67,10 @@ const PRIVATE_API_ACTIONS = new Set<ChannelMessageActionName>([
 ]);
 
 export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
-  describeMessageTool: ({ cfg, currentChannelId }) => {
+  listActions: ({ cfg, currentChannelId }) => {
     const account = resolveBlueBubblesAccount({ cfg: cfg });
     if (!account.enabled || !account.configured) {
-      return null;
+      return [];
     }
     const gate = createActionGate(cfg.channels?.bluebubbles?.actions);
     const actions = new Set<ChannelMessageActionName>();
@@ -107,7 +107,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
         }
       }
     }
-    return { actions: Array.from(actions) };
+    return Array.from(actions);
   },
   supportsAction: ({ action }) => SUPPORTED_ACTIONS.has(action),
   extractToolSend: ({ args }) => extractToolSend(args, "sendMessage"),

extensions/bluebubbles/src/attachments.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import path from "node:path";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { assertMultipartActionOk, postMultipartFormData } from "./multipart.js";
 import {
@@ -7,7 +8,6 @@ import {
   isBlueBubblesPrivateApiStatusEnabled,
 } from "./probe.js";
 import { resolveRequestUrl } from "./request-url.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 import { getBlueBubblesRuntime, warnBlueBubbles } from "./runtime.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";
 import { resolveChatGuidForTarget } from "./send.js";

extensions/bluebubbles/src/channel.ts

@@ -1,11 +1,23 @@
 import { formatNormalizedAllowFromEntries } from "openclaw/plugin-sdk/allow-from";
+import type { ChannelAccountSnapshot, ChannelPlugin } from "openclaw/plugin-sdk/bluebubbles";
 import {
-  createScopedAccountConfigAccessors,
-  createScopedChannelConfigBase,
-  createScopedDmSecurityResolver,
-} from "openclaw/plugin-sdk/channel-config-helpers";
+  buildChannelConfigSchema,
+  buildComputedAccountStatusSnapshot,
+  buildProbeChannelStatusSummary,
+  collectBlueBubblesStatusIssues,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  PAIRING_APPROVED_MESSAGE,
+  resolveBlueBubblesGroupRequireMention,
+  resolveBlueBubblesGroupToolPolicy,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk/bluebubbles";
+import { mapAllowFromEntries } from "openclaw/plugin-sdk/channel-config-helpers";
 import { createAccountStatusSink } from "openclaw/plugin-sdk/channel-lifecycle";
-import { collectOpenGroupPolicyRestrictSendersWarnings } from "openclaw/plugin-sdk/channel-policy";
+import {
+  buildAccountScopedDmSecurityPolicy,
+  collectOpenGroupPolicyRestrictSendersWarnings,
+} from "openclaw/plugin-sdk/channel-policy";
 import { createLazyRuntimeNamedExport } from "openclaw/plugin-sdk/lazy-runtime";
 import {
   listBlueBubblesAccountIds,
@@ -16,26 +28,10 @@ import {
 import { bluebubblesMessageActions } from "./actions.js";
 import type { BlueBubblesProbe } from "./channel.runtime.js";
 import { BlueBubblesConfigSchema } from "./config-schema.js";
-import {
-  resolveBlueBubblesGroupRequireMention,
-  resolveBlueBubblesGroupToolPolicy,
-} from "./group-policy.js";
-import type { ChannelAccountSnapshot, ChannelPlugin } from "./runtime-api.js";
-import {
-  buildChannelConfigSchema,
-  buildComputedAccountStatusSnapshot,
-  buildProbeChannelStatusSummary,
-  collectBlueBubblesStatusIssues,
-  DEFAULT_ACCOUNT_ID,
-  PAIRING_APPROVED_MESSAGE,
-} from "./runtime-api.js";
-import { resolveBlueBubblesOutboundSessionRoute } from "./session-route.js";
 import { blueBubblesSetupAdapter } from "./setup-core.js";
 import { blueBubblesSetupWizard } from "./setup-surface.js";
 import {
   extractHandleFromChatGuid,
-  inferBlueBubblesTargetChatType,
-  looksLikeBlueBubblesExplicitTargetId,
   looksLikeBlueBubblesTargetId,
   normalizeBlueBubblesHandle,
   normalizeBlueBubblesMessagingTarget,
@@ -47,32 +43,6 @@ const loadBlueBubblesChannelRuntime = createLazyRuntimeNamedExport(
   "blueBubblesChannelRuntime",
 );
 
-const bluebubblesConfigAccessors = createScopedAccountConfigAccessors({
-  resolveAccount: ({ cfg, accountId }) => resolveBlueBubblesAccount({ cfg, accountId }),
-  resolveAllowFrom: (account: ResolvedBlueBubblesAccount) => account.config.allowFrom,
-  formatAllowFrom: (allowFrom) =>
-    formatNormalizedAllowFromEntries({
-      allowFrom,
-      normalizeEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
-    }),
-});
-
-const bluebubblesConfigBase = createScopedChannelConfigBase<ResolvedBlueBubblesAccount>({
-  sectionKey: "bluebubbles",
-  listAccountIds: listBlueBubblesAccountIds,
-  resolveAccount: (cfg, accountId) => resolveBlueBubblesAccount({ cfg, accountId }),
-  defaultAccountId: resolveDefaultBlueBubblesAccountId,
-  clearBaseFields: ["serverUrl", "password", "name", "webhookPath"],
-});
-
-const resolveBlueBubblesDmPolicy = createScopedDmSecurityResolver<ResolvedBlueBubblesAccount>({
-  channelKey: "bluebubbles",
-  resolvePolicy: (account) => account.config.dmPolicy,
-  resolveAllowFrom: (account) => account.config.allowFrom,
-  policyPathSuffix: "dmPolicy",
-  normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
-});
-
 const meta = {
   id: "bluebubbles",
   label: "BlueBubbles",
@@ -115,7 +85,24 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
   configSchema: buildChannelConfigSchema(BlueBubblesConfigSchema),
   setupWizard: blueBubblesSetupWizard,
   config: {
-    ...bluebubblesConfigBase,
+    listAccountIds: (cfg) => listBlueBubblesAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveBlueBubblesAccount({ cfg: cfg, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultBlueBubblesAccountId(cfg),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg,
+        sectionKey: "bluebubbles",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg,
+        sectionKey: "bluebubbles",
+        accountId,
+        clearBaseFields: ["serverUrl", "password", "name", "webhookPath"],
+      }),
     isConfigured: (account) => account.configured,
     describeAccount: (account): ChannelAccountSnapshot => ({
       accountId: account.accountId,
@@ -124,11 +111,28 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
       configured: account.configured,
       baseUrl: account.baseUrl,
     }),
-    ...bluebubblesConfigAccessors,
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      mapAllowFromEntries(resolveBlueBubblesAccount({ cfg: cfg, accountId }).config.allowFrom),
+    formatAllowFrom: ({ allowFrom }) =>
+      formatNormalizedAllowFromEntries({
+        allowFrom,
+        normalizeEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
+      }),
   },
   actions: bluebubblesMessageActions,
   security: {
-    resolveDmPolicy: resolveBlueBubblesDmPolicy,
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      return buildAccountScopedDmSecurityPolicy({
+        cfg,
+        channelKey: "bluebubbles",
+        accountId,
+        fallbackAccountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+        policy: account.config.dmPolicy,
+        allowFrom: account.config.allowFrom ?? [],
+        policyPathSuffix: "dmPolicy",
+        normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
+      });
+    },
     collectWarnings: ({ account }) => {
       const groupPolicy = account.config.groupPolicy ?? "allowlist";
       return collectOpenGroupPolicyRestrictSendersWarnings({
@@ -143,26 +147,9 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
   },
   messaging: {
     normalizeTarget: normalizeBlueBubblesMessagingTarget,
-    inferTargetChatType: ({ to }) => inferBlueBubblesTargetChatType(to),
-    resolveOutboundSessionRoute: (params) => resolveBlueBubblesOutboundSessionRoute(params),
     targetResolver: {
-      looksLikeId: looksLikeBlueBubblesExplicitTargetId,
+      looksLikeId: looksLikeBlueBubblesTargetId,
       hint: "<handle|chat_guid:GUID|chat_id:ID|chat_identifier:ID>",
-      resolveTarget: async ({ normalized }) => {
-        const to = normalized?.trim();
-        if (!to) {
-          return null;
-        }
-        const chatType = inferBlueBubblesTargetChatType(to);
-        if (!chatType) {
-          return null;
-        }
-        return {
-          to,
-          kind: chatType === "direct" ? "user" : "group",
-          source: "normalized" as const,
-        };
-      },
     },
     formatTargetDisplay: ({ target, display }) => {
       const shouldParseDisplay = (value: string): boolean => {

extensions/bluebubbles/src/chat.ts

@@ -1,9 +1,9 @@
 import crypto from "node:crypto";
 import path from "node:path";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { assertMultipartActionOk, postMultipartFormData } from "./multipart.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
 
 export type BlueBubblesChatOpts = {

extensions/bluebubbles/src/config-apply.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "./runtime-api.js";
+import { DEFAULT_ACCOUNT_ID, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 
 type BlueBubblesConfigPatch = {
   serverUrl?: string;

extensions/bluebubbles/src/config-schema.ts

@@ -1,3 +1,4 @@
+import { MarkdownConfigSchema, ToolPolicySchema } from "openclaw/plugin-sdk/bluebubbles";
 import {
   AllowFromListSchema,
   buildCatchallMultiAccountChannelSchema,
@@ -5,7 +6,6 @@ import {
   GroupPolicySchema,
 } from "openclaw/plugin-sdk/channel-config-schema";
 import { z } from "zod";
-import { MarkdownConfigSchema, ToolPolicySchema } from "./runtime-api.js";
 import { buildSecretInputSchema, hasConfiguredSecretInput } from "./secret-input.js";
 
 const bluebubblesActionSchema = z

extensions/bluebubbles/src/group-policy.test.ts

@@ -1,36 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  resolveBlueBubblesGroupRequireMention,
-  resolveBlueBubblesGroupToolPolicy,
-} from "./group-policy.js";
-
-describe("bluebubbles group policy", () => {
-  it("uses generic channel group policy helpers", () => {
-    const cfg = {
-      channels: {
-        bluebubbles: {
-          groups: {
-            "chat:primary": {
-              requireMention: false,
-              tools: { deny: ["exec"] },
-            },
-            "*": {
-              requireMention: true,
-              tools: { allow: ["message.send"] },
-            },
-          },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    expect(resolveBlueBubblesGroupRequireMention({ cfg, groupId: "chat:primary" })).toBe(false);
-    expect(resolveBlueBubblesGroupRequireMention({ cfg, groupId: "chat:other" })).toBe(true);
-    expect(resolveBlueBubblesGroupToolPolicy({ cfg, groupId: "chat:primary" })).toEqual({
-      deny: ["exec"],
-    });
-    expect(resolveBlueBubblesGroupToolPolicy({ cfg, groupId: "chat:other" })).toEqual({
-      allow: ["message.send"],
-    });
-  });
-});

extensions/bluebubbles/src/group-policy.ts

@@ -1,40 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
-import {
-  resolveChannelGroupRequireMention,
-  resolveChannelGroupToolsPolicy,
-  type GroupToolPolicyConfig,
-} from "openclaw/plugin-sdk/channel-policy";
-
-type BlueBubblesGroupContext = {
-  cfg: OpenClawConfig;
-  accountId?: string | null;
-  groupId?: string | null;
-  senderId?: string | null;
-  senderName?: string | null;
-  senderUsername?: string | null;
-  senderE164?: string | null;
-};
-
-export function resolveBlueBubblesGroupRequireMention(params: BlueBubblesGroupContext): boolean {
-  return resolveChannelGroupRequireMention({
-    cfg: params.cfg,
-    channel: "bluebubbles",
-    groupId: params.groupId,
-    accountId: params.accountId,
-  });
-}
-
-export function resolveBlueBubblesGroupToolPolicy(
-  params: BlueBubblesGroupContext,
-): GroupToolPolicyConfig | undefined {
-  return resolveChannelGroupToolsPolicy({
-    cfg: params.cfg,
-    channel: "bluebubbles",
-    groupId: params.groupId,
-    accountId: params.accountId,
-    senderId: params.senderId,
-    senderName: params.senderName,
-    senderUsername: params.senderUsername,
-    senderE164: params.senderE164,
-  });
-}

extensions/bluebubbles/src/history.ts

@@ -1,5 +1,5 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
 
 export type BlueBubblesHistoryEntry = {

extensions/bluebubbles/src/media-send.ts

@@ -3,10 +3,10 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveChannelMediaMaxBytes, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import { sendBlueBubblesAttachment } from "./attachments.js";
 import { resolveBlueBubblesMessageId } from "./monitor.js";
-import { resolveChannelMediaMaxBytes, type OpenClawConfig } from "./runtime-api.js";
 import { getBlueBubblesRuntime } from "./runtime.js";
 import { sendMessageBlueBubbles } from "./send.js";
 

extensions/bluebubbles/src/monitor-debounce.ts

@@ -1,6 +1,6 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import type { NormalizedWebhookMessage } from "./monitor-normalize.js";
 import type { BlueBubblesCoreRuntime, WebhookTarget } from "./monitor-shared.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 
 /**
  * Entry type for debouncing inbound messages.

extensions/bluebubbles/src/monitor-normalize.ts

@@ -1,4 +1,4 @@
-import { parseFiniteNumber } from "./runtime-api.js";
+import { parseFiniteNumber } from "openclaw/plugin-sdk/bluebubbles";
 import { extractHandleFromChatGuid, normalizeBlueBubblesHandle } from "./targets.js";
 import type { BlueBubblesAttachment } from "./types.js";
 

extensions/bluebubbles/src/monitor-processing.ts

@@ -1,3 +1,22 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+import {
+  DM_GROUP_ACCESS_REASON,
+  createScopedPairingAccess,
+  createReplyPrefixOptions,
+  evictOldHistoryKeys,
+  issuePairingChallenge,
+  logAckFailure,
+  logInboundDrop,
+  logTypingFailure,
+  mapAllowFromEntries,
+  readStoreAllowFromForDmPolicy,
+  recordPendingHistoryEntryIfEnabled,
+  resolveAckReaction,
+  resolveDmGroupAccessWithLists,
+  resolveControlCommandGate,
+  stripMarkdown,
+  type HistoryEntry,
+} from "openclaw/plugin-sdk/bluebubbles";
 import { downloadBlueBubblesAttachment } from "./attachments.js";
 import { markBlueBubblesChatRead, sendBlueBubblesTyping } from "./chat.js";
 import { fetchBlueBubblesHistory } from "./history.js";
@@ -30,25 +49,6 @@ import type {
 } from "./monitor-shared.js";
 import { isBlueBubblesPrivateApiEnabled } from "./probe.js";
 import { normalizeBlueBubblesReactionInput, sendBlueBubblesReaction } from "./reactions.js";
-import type { OpenClawConfig } from "./runtime-api.js";
-import {
-  DM_GROUP_ACCESS_REASON,
-  createScopedPairingAccess,
-  createReplyPrefixOptions,
-  evictOldHistoryKeys,
-  issuePairingChallenge,
-  logAckFailure,
-  logInboundDrop,
-  logTypingFailure,
-  mapAllowFromEntries,
-  readStoreAllowFromForDmPolicy,
-  recordPendingHistoryEntryIfEnabled,
-  resolveAckReaction,
-  resolveDmGroupAccessWithLists,
-  resolveControlCommandGate,
-  stripMarkdown,
-  type HistoryEntry,
-} from "./runtime-api.js";
 import { normalizeSecretInputString } from "./secret-input.js";
 import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import {

extensions/bluebubbles/src/monitor-shared.ts

@@ -1,5 +1,5 @@
+import { normalizeWebhookPath, type OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import type { ResolvedBlueBubblesAccount } from "./accounts.js";
-import { normalizeWebhookPath, type OpenClawConfig } from "./runtime-api.js";
 import { getBlueBubblesRuntime } from "./runtime.js";
 import type { BlueBubblesAccountConfig } from "./types.js";
 

extensions/bluebubbles/src/monitor.ts

@@ -1,5 +1,12 @@
 import { timingSafeEqual } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  createWebhookInFlightLimiter,
+  registerWebhookTargetWithPluginRoute,
+  readWebhookBodyOrReject,
+  resolveWebhookTargetWithAuthOrRejectSync,
+  withResolvedWebhookRequestPipeline,
+} from "openclaw/plugin-sdk/bluebubbles";
 import { createBlueBubblesDebounceRegistry } from "./monitor-debounce.js";
 import { normalizeWebhookMessage, normalizeWebhookReaction } from "./monitor-normalize.js";
 import { logVerbose, processMessage, processReaction } from "./monitor-processing.js";
@@ -15,13 +22,6 @@ import {
   type WebhookTarget,
 } from "./monitor-shared.js";
 import { fetchBlueBubblesServerInfo } from "./probe.js";
-import {
-  createWebhookInFlightLimiter,
-  registerWebhookTargetWithPluginRoute,
-  readWebhookBodyOrReject,
-  resolveWebhookTargetWithAuthOrRejectSync,
-  withResolvedWebhookRequestPipeline,
-} from "./runtime-api.js";
 import { getBlueBubblesRuntime } from "./runtime.js";
 
 const webhookTargets = new Map<string, WebhookTarget[]>();

extensions/bluebubbles/src/probe.ts

@@ -1,4 +1,4 @@
-import type { BaseProbeResult } from "./runtime-api.js";
+import type { BaseProbeResult } from "openclaw/plugin-sdk/bluebubbles";
 import { normalizeSecretInputString } from "./secret-input.js";
 import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
 
@@ -73,7 +73,7 @@ export async function fetchBlueBubblesServerInfo(params: {
 }
 
 /**
- * Get cached server info synchronously (for use in describeMessageTool).
+ * Get cached server info synchronously (for use in listActions).
  * Returns null if not cached or expired.
  */
 export function getCachedBlueBubblesServerInfo(accountId?: string): BlueBubblesServerInfo | null {

extensions/bluebubbles/src/reactions.ts

@@ -1,6 +1,6 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesServerAccount } from "./account-resolve.js";
 import { getCachedBlueBubblesPrivateApiStatus } from "./probe.js";
-import type { OpenClawConfig } from "./runtime-api.js";
 import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
 
 export type BlueBubblesReactionOpts = {

extensions/bluebubbles/src/request-url.ts

@@ -1 +1 @@
-export { resolveRequestUrl } from "./runtime-api.js";
+export { resolveRequestUrl } from "openclaw/plugin-sdk/bluebubbles";

extensions/bluebubbles/src/runtime-api.ts

@@ -1 +0,0 @@
-export * from "openclaw/plugin-sdk/bluebubbles";

extensions/bluebubbles/src/runtime.ts

@@ -1,5 +1,5 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/bluebubbles";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
-import type { PluginRuntime } from "./runtime-api.js";
 
 const runtimeStore = createPluginRuntimeStore<PluginRuntime>("BlueBubbles runtime not initialized");
 type LegacyRuntimeLogShape = { log?: (message: string) => void };

extensions/bluebubbles/src/secret-input.ts

@@ -3,7 +3,7 @@ import {
   hasConfiguredSecretInput,
   normalizeResolvedSecretInputString,
   normalizeSecretInputString,
-} from "./runtime-api.js";
+} from "openclaw/plugin-sdk/bluebubbles";
 
 export {
   buildSecretInputSchema,

extensions/bluebubbles/src/send.ts

@@ -1,11 +1,11 @@
 import crypto from "node:crypto";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/bluebubbles";
+import { stripMarkdown } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
 import {
   getCachedBlueBubblesPrivateApiStatus,
   isBlueBubblesPrivateApiStatusEnabled,
 } from "./probe.js";
-import type { OpenClawConfig } from "./runtime-api.js";
-import { stripMarkdown } from "./runtime-api.js";
 import { warnBlueBubbles } from "./runtime.js";
 import { normalizeSecretInputString } from "./secret-input.js";
 import { extractBlueBubblesMessageId, resolveBlueBubblesSendTarget } from "./send-helpers.js";

extensions/bluebubbles/src/session-route.ts

@@ -1,37 +0,0 @@
-import {
-  buildChannelOutboundSessionRoute,
-  stripChannelTargetPrefix,
-  type ChannelOutboundSessionRouteParams,
-} from "openclaw/plugin-sdk/core";
-import { parseBlueBubblesTarget } from "./targets.js";
-
-export function resolveBlueBubblesOutboundSessionRoute(params: ChannelOutboundSessionRouteParams) {
-  const stripped = stripChannelTargetPrefix(params.target, "bluebubbles");
-  if (!stripped) {
-    return null;
-  }
-  const parsed = parseBlueBubblesTarget(stripped);
-  const isGroup =
-    parsed.kind === "chat_id" || parsed.kind === "chat_guid" || parsed.kind === "chat_identifier";
-  const peerId =
-    parsed.kind === "chat_id"
-      ? String(parsed.chatId)
-      : parsed.kind === "chat_guid"
-        ? parsed.chatGuid
-        : parsed.kind === "chat_identifier"
-          ? parsed.chatIdentifier
-          : parsed.to;
-  return buildChannelOutboundSessionRoute({
-    cfg: params.cfg,
-    agentId: params.agentId,
-    channel: "bluebubbles",
-    accountId: params.accountId,
-    peer: {
-      kind: isGroup ? "group" : "direct",
-      id: peerId,
-    },
-    chatType: isGroup ? "group" : "direct",
-    from: isGroup ? `group:${peerId}` : `bluebubbles:${peerId}`,
-    to: `bluebubbles:${stripped}`,
-  });
-}

extensions/bluebubbles/src/setup-core.ts

@@ -1,8 +1,8 @@
 import {
-  createTopLevelChannelDmPolicySetter,
   normalizeAccountId,
   patchScopedAccountConfig,
   prepareScopedSetupConfig,
+  setTopLevelChannelDmPolicyWithAllowFrom,
   type ChannelSetupAdapter,
   type DmPolicy,
   type OpenClawConfig,
@@ -10,12 +10,13 @@ import {
 import { applyBlueBubblesConnectionConfig } from "./config-apply.js";
 
 const channel = "bluebubbles" as const;
-const setBlueBubblesTopLevelDmPolicy = createTopLevelChannelDmPolicySetter({
-  channel,
-});
 
 export function setBlueBubblesDmPolicy(cfg: OpenClawConfig, dmPolicy: DmPolicy): OpenClawConfig {
-  return setBlueBubblesTopLevelDmPolicy(cfg, dmPolicy);
+  return setTopLevelChannelDmPolicyWithAllowFrom({
+    cfg,
+    channel,
+    dmPolicy,
+  });
 }
 
 export function setBlueBubblesAllowFrom(

extensions/bluebubbles/src/setup-surface.ts

@@ -1,10 +1,11 @@
 import {
-  createAllowFromSection,
   DEFAULT_ACCOUNT_ID,
   formatDocsLink,
-  promptParsedAllowFromForAccount,
+  mergeAllowFromEntries,
+  resolveSetupAccountId,
   type ChannelSetupDmPolicy,
   type ChannelSetupWizard,
+  type DmPolicy,
   type OpenClawConfig,
   type WizardPrompter,
 } from "openclaw/plugin-sdk/setup";
@@ -54,13 +55,14 @@ async function promptBlueBubblesAllowFrom(params: {
   prompter: WizardPrompter;
   accountId?: string;
 }): Promise<OpenClawConfig> {
-  return await promptParsedAllowFromForAccount({
-    cfg: params.cfg,
+  const accountId = resolveSetupAccountId({
     accountId: params.accountId,
     defaultAccountId: resolveDefaultBlueBubblesAccountId(params.cfg),
-    prompter: params.prompter,
-    noteTitle: "BlueBubbles allowlist",
-    noteLines: [
+  });
+  const resolved = resolveBlueBubblesAccount({ cfg: params.cfg, accountId });
+  const existing = resolved.config.allowFrom ?? [];
+  await params.prompter.note(
+    [
       "Allowlist BlueBubbles DMs by handle or chat target.",
       "Examples:",
       "- +15555550123",
@@ -69,23 +71,30 @@ async function promptBlueBubblesAllowFrom(params: {
       "- chat_guid:iMessage;-;+15555550123",
       "Multiple entries: comma- or newline-separated.",
       `Docs: ${formatDocsLink("/channels/bluebubbles", "bluebubbles")}`,
-    ],
+    ].join("\n"),
+    "BlueBubbles allowlist",
+  );
+  const entry = await params.prompter.text({
     message: "BlueBubbles allowFrom (handle or chat_id)",
     placeholder: "+15555550123, user@example.com, chat_id:123",
-    parseEntries: (raw) => {
-      const entries = parseBlueBubblesAllowFromInput(raw);
-      for (const entry of entries) {
-        if (!validateBlueBubblesAllowFromEntry(entry)) {
-          return { entries: [], error: `Invalid entry: ${entry}` };
+    initialValue: existing[0] ? String(existing[0]) : undefined,
+    validate: (value) => {
+      const raw = String(value ?? "").trim();
+      if (!raw) {
+        return "Required";
+      }
+      const parts = parseBlueBubblesAllowFromInput(raw);
+      for (const part of parts) {
+        if (!validateBlueBubblesAllowFromEntry(part)) {
+          return `Invalid entry: ${part}`;
         }
       }
-      return { entries };
+      return undefined;
     },
-    getExistingAllowFrom: ({ cfg, accountId }) =>
-      resolveBlueBubblesAccount({ cfg, accountId }).config.allowFrom ?? [],
-    applyAllowFrom: ({ cfg, accountId, allowFrom }) =>
-      setBlueBubblesAllowFrom(cfg, accountId, allowFrom),
   });
+  const parts = parseBlueBubblesAllowFromInput(String(entry));
+  const unique = mergeAllowFromEntries(undefined, parts);
+  return setBlueBubblesAllowFrom(params.cfg, accountId, unique);
 }
 
 function validateBlueBubblesServerUrlInput(value: unknown): string | undefined {
@@ -263,7 +272,7 @@ export const blueBubblesSetupWizard: ChannelSetupWizard = {
     ],
   },
   dmPolicy,
-  allowFrom: createAllowFromSection({
+  allowFrom: {
     helpTitle: "BlueBubbles allowlist",
     helpLines: [
       "Allowlist BlueBubbles DMs by handle or chat target.",
@@ -281,9 +290,15 @@ export const blueBubblesSetupWizard: ChannelSetupWizard = {
       "Use a BlueBubbles handle or chat target like +15555550123 or chat_id:123.",
     parseInputs: parseBlueBubblesAllowFromInput,
     parseId: (raw) => validateBlueBubblesAllowFromEntry(raw),
+    resolveEntries: async ({ entries }) =>
+      entries.map((entry) => ({
+        input: entry,
+        resolved: Boolean(validateBlueBubblesAllowFromEntry(entry)),
+        id: validateBlueBubblesAllowFromEntry(entry),
+      })),
     apply: async ({ cfg, accountId, allowFrom }) =>
       setBlueBubblesAllowFrom(cfg, accountId, allowFrom),
-  }),
+  },
   disable: (cfg) => ({
     ...cfg,
     channels: {

extensions/bluebubbles/src/targets.test.ts

@@ -1,7 +1,5 @@
 import { describe, expect, it } from "vitest";
 import {
-  inferBlueBubblesTargetChatType,
-  looksLikeBlueBubblesExplicitTargetId,
   isAllowedBlueBubblesSender,
   looksLikeBlueBubblesTargetId,
   normalizeBlueBubblesMessagingTarget,
@@ -103,30 +101,6 @@ describe("looksLikeBlueBubblesTargetId", () => {
   });
 });
 
-describe("looksLikeBlueBubblesExplicitTargetId", () => {
-  it("treats explicit chat targets as immediate ids", () => {
-    expect(looksLikeBlueBubblesExplicitTargetId("chat_guid:ABC-123")).toBe(true);
-    expect(looksLikeBlueBubblesExplicitTargetId("imessage:+15551234567")).toBe(true);
-  });
-
-  it("prefers directory fallback for bare handles and phone numbers", () => {
-    expect(looksLikeBlueBubblesExplicitTargetId("+1 (555) 123-4567")).toBe(false);
-    expect(looksLikeBlueBubblesExplicitTargetId("user@example.com")).toBe(false);
-  });
-});
-
-describe("inferBlueBubblesTargetChatType", () => {
-  it("infers direct chat for handles and dm chat_guids", () => {
-    expect(inferBlueBubblesTargetChatType("+15551234567")).toBe("direct");
-    expect(inferBlueBubblesTargetChatType("chat_guid:iMessage;-;+15551234567")).toBe("direct");
-  });
-
-  it("infers group chat for explicit group targets", () => {
-    expect(inferBlueBubblesTargetChatType("chat_id:123")).toBe("group");
-    expect(inferBlueBubblesTargetChatType("chat_guid:iMessage;+;chat123")).toBe("group");
-  });
-});
-
 describe("parseBlueBubblesTarget", () => {
   it("parses chat<digits> pattern as chat_identifier", () => {
     expect(parseBlueBubblesTarget("chat660250192681427962")).toEqual({

extensions/bluebubbles/src/targets.ts

@@ -5,7 +5,7 @@ import {
   type ParsedChatTarget,
   resolveServicePrefixedAllowTarget,
   resolveServicePrefixedTarget,
-} from "./runtime-api.js";
+} from "openclaw/plugin-sdk/bluebubbles";
 
 export type BlueBubblesService = "imessage" | "sms" | "auto";
 
@@ -237,63 +237,6 @@ export function looksLikeBlueBubblesTargetId(raw: string, normalized?: string):
   return false;
 }
 
-export function looksLikeBlueBubblesExplicitTargetId(raw: string, normalized?: string): boolean {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return false;
-  }
-  const candidate = stripBlueBubblesPrefix(trimmed);
-  if (!candidate) {
-    return false;
-  }
-  const lowered = candidate.toLowerCase();
-  if (/^(imessage|sms|auto):/.test(lowered)) {
-    return true;
-  }
-  if (
-    /^(chat_id|chatid|chat|chat_guid|chatguid|guid|chat_identifier|chatidentifier|chatident|group):/.test(
-      lowered,
-    )
-  ) {
-    return true;
-  }
-  if (parseRawChatGuid(candidate) || looksLikeRawChatIdentifier(candidate)) {
-    return true;
-  }
-  if (normalized) {
-    const normalizedTrimmed = normalized.trim();
-    if (!normalizedTrimmed) {
-      return false;
-    }
-    const normalizedLower = normalizedTrimmed.toLowerCase();
-    if (
-      /^(imessage|sms|auto):/.test(normalizedLower) ||
-      /^(chat_id|chat_guid|chat_identifier):/.test(normalizedLower)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-export function inferBlueBubblesTargetChatType(raw: string): "direct" | "group" | undefined {
-  try {
-    const parsed = parseBlueBubblesTarget(raw);
-    if (parsed.kind === "handle") {
-      return "direct";
-    }
-    if (parsed.kind === "chat_guid") {
-      return parsed.chatGuid.includes(";+;") ? "group" : "direct";
-    }
-    if (parsed.kind === "chat_id" || parsed.kind === "chat_identifier") {
-      return "group";
-    }
-  } catch {
-    return undefined;
-  }
-  return undefined;
-}
-
 export function parseBlueBubblesTarget(raw: string): BlueBubblesTarget {
   const trimmed = stripBlueBubblesPrefix(raw);
   if (!trimmed) {

extensions/bluebubbles/src/types.ts

@@ -1,6 +1,6 @@
-import type { DmPolicy, GroupPolicy } from "./runtime-api.js";
+import type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk/bluebubbles";
 
-export type { DmPolicy, GroupPolicy } from "./runtime-api.js";
+export type { DmPolicy, GroupPolicy } from "openclaw/plugin-sdk/bluebubbles";
 
 export type BlueBubblesGroupConfig = {
   /** If true, only respond in this group when mentioned. */

extensions/brave/index.ts

@@ -1,11 +1,28 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/core";
-import { createBraveWebSearchProvider } from "./src/brave-web-search-provider.js";
+import {
+  createPluginBackedWebSearchProvider,
+  getTopLevelCredentialValue,
+  setTopLevelCredentialValue,
+} from "openclaw/plugin-sdk/provider-web-search";
 
 export default definePluginEntry({
   id: "brave",
   name: "Brave Plugin",
   description: "Bundled Brave plugin",
   register(api) {
-    api.registerWebSearchProvider(createBraveWebSearchProvider());
+    api.registerWebSearchProvider(
+      createPluginBackedWebSearchProvider({
+        id: "brave",
+        label: "Brave Search",
+        hint: "Structured results · country/language/time filters",
+        envVars: ["BRAVE_API_KEY"],
+        placeholder: "BSA...",
+        signupUrl: "https://brave.com/search/api/",
+        docsUrl: "https://docs.openclaw.ai/brave-search",
+        autoDetectOrder: 10,
+        getCredentialValue: getTopLevelCredentialValue,
+        setCredentialValue: setTopLevelCredentialValue,
+      }),
+    );
   },
 });

extensions/brave/openclaw.plugin.json

@@ -1,34 +1,8 @@
 {
   "id": "brave",
-  "uiHints": {
-    "webSearch.apiKey": {
-      "label": "Brave Search API Key",
-      "help": "Brave Search API key (fallback: BRAVE_API_KEY env var).",
-      "sensitive": true,
-      "placeholder": "BSA..."
-    },
-    "webSearch.mode": {
-      "label": "Brave Search Mode",
-      "help": "Brave Search mode: web or llm-context."
-    }
-  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {
-      "webSearch": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "apiKey": {
-            "type": ["string", "object"]
-          },
-          "mode": {
-            "type": "string",
-            "enum": ["web", "llm-context"]
-          }
-        }
-      }
-    }
+    "properties": {}
   }
 }

extensions/brave/src/brave-web-search-provider.ts

@@ -1,648 +0,0 @@
-import { Type } from "@sinclair/typebox";
-import { readNumberParam, readStringParam } from "../../../src/agents/tools/common.js";
-import type { SearchConfigRecord } from "../../../src/agents/tools/web-search-provider-common.js";
-import {
-  buildSearchCacheKey,
-  DEFAULT_SEARCH_COUNT,
-  MAX_SEARCH_COUNT,
-  normalizeFreshness,
-  normalizeToIsoDate,
-  readCachedSearchPayload,
-  readConfiguredSecretString,
-  readProviderEnvValue,
-  resolveSearchCacheTtlMs,
-  resolveSearchCount,
-  resolveSearchTimeoutSeconds,
-  resolveSiteName,
-  withTrustedWebSearchEndpoint,
-  writeCachedSearchPayload,
-} from "../../../src/agents/tools/web-search-provider-common.js";
-import {
-  resolveProviderWebSearchPluginConfig,
-  setProviderWebSearchPluginConfigValue,
-} from "../../../src/agents/tools/web-search-provider-config.js";
-import { formatCliCommand } from "../../../src/cli/command-format.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import type {
-  WebSearchProviderPlugin,
-  WebSearchProviderToolDefinition,
-} from "../../../src/plugins/types.js";
-import { wrapWebContent } from "../../../src/security/external-content.js";
-
-const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
-const BRAVE_LLM_CONTEXT_ENDPOINT = "https://api.search.brave.com/res/v1/llm/context";
-const BRAVE_SEARCH_LANG_CODES = new Set([
-  "ar",
-  "eu",
-  "bn",
-  "bg",
-  "ca",
-  "zh-hans",
-  "zh-hant",
-  "hr",
-  "cs",
-  "da",
-  "nl",
-  "en",
-  "en-gb",
-  "et",
-  "fi",
-  "fr",
-  "gl",
-  "de",
-  "el",
-  "gu",
-  "he",
-  "hi",
-  "hu",
-  "is",
-  "it",
-  "jp",
-  "kn",
-  "ko",
-  "lv",
-  "lt",
-  "ms",
-  "ml",
-  "mr",
-  "nb",
-  "pl",
-  "pt-br",
-  "pt-pt",
-  "pa",
-  "ro",
-  "ru",
-  "sr",
-  "sk",
-  "sl",
-  "es",
-  "sv",
-  "ta",
-  "te",
-  "th",
-  "tr",
-  "uk",
-  "vi",
-]);
-const BRAVE_SEARCH_LANG_ALIASES: Record<string, string> = {
-  ja: "jp",
-  zh: "zh-hans",
-  "zh-cn": "zh-hans",
-  "zh-hk": "zh-hant",
-  "zh-sg": "zh-hans",
-  "zh-tw": "zh-hant",
-};
-const BRAVE_UI_LANG_LOCALE = /^([a-z]{2})-([a-z]{2})$/i;
-
-type BraveConfig = {
-  apiKey?: unknown;
-  mode?: string;
-};
-
-type BraveSearchResult = {
-  title?: string;
-  url?: string;
-  description?: string;
-  age?: string;
-};
-
-type BraveSearchResponse = {
-  web?: {
-    results?: BraveSearchResult[];
-  };
-};
-
-type BraveLlmContextResult = { url: string; title: string; snippets: string[] };
-type BraveLlmContextResponse = {
-  grounding: { generic?: BraveLlmContextResult[] };
-  sources?: { url?: string; hostname?: string; date?: string }[];
-};
-
-function resolveBraveConfig(
-  config?: OpenClawConfig,
-  searchConfig?: SearchConfigRecord,
-): BraveConfig {
-  const pluginConfig = resolveProviderWebSearchPluginConfig(config, "brave");
-  if (pluginConfig) {
-    return pluginConfig as BraveConfig;
-  }
-  const scoped = (searchConfig as Record<string, unknown> | undefined)?.brave;
-  return scoped && typeof scoped === "object" && !Array.isArray(scoped)
-    ? ({
-        ...(scoped as BraveConfig),
-        apiKey: (searchConfig as Record<string, unknown> | undefined)?.apiKey,
-      } as BraveConfig)
-    : ({ apiKey: (searchConfig as Record<string, unknown> | undefined)?.apiKey } as BraveConfig);
-}
-
-function resolveBraveMode(brave: BraveConfig): "web" | "llm-context" {
-  return brave.mode === "llm-context" ? "llm-context" : "web";
-}
-
-function resolveBraveApiKey(
-  config?: OpenClawConfig,
-  searchConfig?: SearchConfigRecord,
-): string | undefined {
-  const braveConfig = resolveBraveConfig(config, searchConfig);
-  return (
-    readConfiguredSecretString(
-      braveConfig.apiKey,
-      "plugins.entries.brave.config.webSearch.apiKey",
-    ) ??
-    readConfiguredSecretString(
-      (searchConfig as Record<string, unknown> | undefined)?.apiKey,
-      "tools.web.search.apiKey",
-    ) ??
-    readProviderEnvValue(["BRAVE_API_KEY"])
-  );
-}
-
-function normalizeBraveSearchLang(value: string | undefined): string | undefined {
-  if (!value) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-  const canonical = BRAVE_SEARCH_LANG_ALIASES[trimmed.toLowerCase()] ?? trimmed.toLowerCase();
-  if (!BRAVE_SEARCH_LANG_CODES.has(canonical)) {
-    return undefined;
-  }
-  return canonical;
-}
-
-function normalizeBraveUiLang(value: string | undefined): string | undefined {
-  if (!value) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-  const match = trimmed.match(BRAVE_UI_LANG_LOCALE);
-  if (!match) {
-    return undefined;
-  }
-  const [, language, region] = match;
-  return `${language.toLowerCase()}-${region.toUpperCase()}`;
-}
-
-function normalizeBraveLanguageParams(params: { search_lang?: string; ui_lang?: string }): {
-  search_lang?: string;
-  ui_lang?: string;
-  invalidField?: "search_lang" | "ui_lang";
-} {
-  const rawSearchLang = params.search_lang?.trim() || undefined;
-  const rawUiLang = params.ui_lang?.trim() || undefined;
-  let searchLangCandidate = rawSearchLang;
-  let uiLangCandidate = rawUiLang;
-
-  if (normalizeBraveUiLang(rawSearchLang) && normalizeBraveSearchLang(rawUiLang)) {
-    searchLangCandidate = rawUiLang;
-    uiLangCandidate = rawSearchLang;
-  }
-
-  const search_lang = normalizeBraveSearchLang(searchLangCandidate);
-  if (searchLangCandidate && !search_lang) {
-    return { invalidField: "search_lang" };
-  }
-
-  const ui_lang = normalizeBraveUiLang(uiLangCandidate);
-  if (uiLangCandidate && !ui_lang) {
-    return { invalidField: "ui_lang" };
-  }
-
-  return { search_lang, ui_lang };
-}
-
-function mapBraveLlmContextResults(
-  data: BraveLlmContextResponse,
-): { url: string; title: string; snippets: string[]; siteName?: string }[] {
-  const genericResults = Array.isArray(data.grounding?.generic) ? data.grounding.generic : [];
-  return genericResults.map((entry) => ({
-    url: entry.url ?? "",
-    title: entry.title ?? "",
-    snippets: (entry.snippets ?? []).filter((s) => typeof s === "string" && s.length > 0),
-    siteName: resolveSiteName(entry.url) || undefined,
-  }));
-}
-
-async function runBraveLlmContextSearch(params: {
-  query: string;
-  apiKey: string;
-  timeoutSeconds: number;
-  country?: string;
-  search_lang?: string;
-  freshness?: string;
-}): Promise<{
-  results: Array<{
-    url: string;
-    title: string;
-    snippets: string[];
-    siteName?: string;
-  }>;
-  sources?: BraveLlmContextResponse["sources"];
-}> {
-  const url = new URL(BRAVE_LLM_CONTEXT_ENDPOINT);
-  url.searchParams.set("q", params.query);
-  if (params.country) {
-    url.searchParams.set("country", params.country);
-  }
-  if (params.search_lang) {
-    url.searchParams.set("search_lang", params.search_lang);
-  }
-  if (params.freshness) {
-    url.searchParams.set("freshness", params.freshness);
-  }
-
-  return withTrustedWebSearchEndpoint(
-    {
-      url: url.toString(),
-      timeoutSeconds: params.timeoutSeconds,
-      init: {
-        method: "GET",
-        headers: {
-          Accept: "application/json",
-          "X-Subscription-Token": params.apiKey,
-        },
-      },
-    },
-    async (res) => {
-      if (!res.ok) {
-        const detail = await res.text();
-        throw new Error(`Brave LLM Context API error (${res.status}): ${detail || res.statusText}`);
-      }
-
-      const data = (await res.json()) as BraveLlmContextResponse;
-      return { results: mapBraveLlmContextResults(data), sources: data.sources };
-    },
-  );
-}
-
-async function runBraveWebSearch(params: {
-  query: string;
-  count: number;
-  apiKey: string;
-  timeoutSeconds: number;
-  country?: string;
-  search_lang?: string;
-  ui_lang?: string;
-  freshness?: string;
-  dateAfter?: string;
-  dateBefore?: string;
-}): Promise<Array<Record<string, unknown>>> {
-  const url = new URL(BRAVE_SEARCH_ENDPOINT);
-  url.searchParams.set("q", params.query);
-  url.searchParams.set("count", String(params.count));
-  if (params.country) {
-    url.searchParams.set("country", params.country);
-  }
-  if (params.search_lang) {
-    url.searchParams.set("search_lang", params.search_lang);
-  }
-  if (params.ui_lang) {
-    url.searchParams.set("ui_lang", params.ui_lang);
-  }
-  if (params.freshness) {
-    url.searchParams.set("freshness", params.freshness);
-  } else if (params.dateAfter && params.dateBefore) {
-    url.searchParams.set("freshness", `${params.dateAfter}to${params.dateBefore}`);
-  } else if (params.dateAfter) {
-    url.searchParams.set(
-      "freshness",
-      `${params.dateAfter}to${new Date().toISOString().slice(0, 10)}`,
-    );
-  } else if (params.dateBefore) {
-    url.searchParams.set("freshness", `1970-01-01to${params.dateBefore}`);
-  }
-
-  return withTrustedWebSearchEndpoint(
-    {
-      url: url.toString(),
-      timeoutSeconds: params.timeoutSeconds,
-      init: {
-        method: "GET",
-        headers: {
-          Accept: "application/json",
-          "X-Subscription-Token": params.apiKey,
-        },
-      },
-    },
-    async (res) => {
-      if (!res.ok) {
-        const detail = await res.text();
-        throw new Error(`Brave Search API error (${res.status}): ${detail || res.statusText}`);
-      }
-
-      const data = (await res.json()) as BraveSearchResponse;
-      const results = Array.isArray(data.web?.results) ? (data.web?.results ?? []) : [];
-      return results.map((entry) => {
-        const description = entry.description ?? "";
-        const title = entry.title ?? "";
-        const url = entry.url ?? "";
-        return {
-          title: title ? wrapWebContent(title, "web_search") : "",
-          url,
-          description: description ? wrapWebContent(description, "web_search") : "",
-          published: entry.age || undefined,
-          siteName: resolveSiteName(url) || undefined,
-        };
-      });
-    },
-  );
-}
-
-function createBraveSchema() {
-  return Type.Object({
-    query: Type.String({ description: "Search query string." }),
-    count: Type.Optional(
-      Type.Number({
-        description: "Number of results to return (1-10).",
-        minimum: 1,
-        maximum: MAX_SEARCH_COUNT,
-      }),
-    ),
-    country: Type.Optional(
-      Type.String({
-        description:
-          "2-letter country code for region-specific results (e.g., 'DE', 'US', 'ALL'). Default: 'US'.",
-      }),
-    ),
-    language: Type.Optional(
-      Type.String({
-        description: "ISO 639-1 language code for results (e.g., 'en', 'de', 'fr').",
-      }),
-    ),
-    freshness: Type.Optional(
-      Type.String({
-        description: "Filter by time: 'day' (24h), 'week', 'month', or 'year'.",
-      }),
-    ),
-    date_after: Type.Optional(
-      Type.String({
-        description: "Only results published after this date (YYYY-MM-DD).",
-      }),
-    ),
-    date_before: Type.Optional(
-      Type.String({
-        description: "Only results published before this date (YYYY-MM-DD).",
-      }),
-    ),
-    search_lang: Type.Optional(
-      Type.String({
-        description:
-          "Brave language code for search results (e.g., 'en', 'de', 'en-gb', 'zh-hans', 'zh-hant', 'pt-br').",
-      }),
-    ),
-    ui_lang: Type.Optional(
-      Type.String({
-        description:
-          "Locale code for UI elements in language-region format (e.g., 'en-US', 'de-DE', 'fr-FR', 'tr-TR'). Must include region subtag.",
-      }),
-    ),
-  });
-}
-
-function missingBraveKeyPayload() {
-  return {
-    error: "missing_brave_api_key",
-    message: `web_search (brave) needs a Brave Search API key. Run \`${formatCliCommand("openclaw configure --section web")}\` to store it, or set BRAVE_API_KEY in the Gateway environment.`,
-    docs: "https://docs.openclaw.ai/tools/web",
-  };
-}
-
-function createBraveToolDefinition(
-  config?: OpenClawConfig,
-  searchConfig?: SearchConfigRecord,
-): WebSearchProviderToolDefinition {
-  const braveConfig = resolveBraveConfig(config, searchConfig);
-  const braveMode = resolveBraveMode(braveConfig);
-
-  return {
-    description:
-      braveMode === "llm-context"
-        ? "Search the web using Brave Search LLM Context API. Returns pre-extracted page content (text chunks, tables, code blocks) optimized for LLM grounding."
-        : "Search the web using Brave Search API. Supports region-specific and localized search via country and language parameters. Returns titles, URLs, and snippets for fast research.",
-    parameters: createBraveSchema(),
-    execute: async (args) => {
-      const apiKey = resolveBraveApiKey(config, searchConfig);
-      if (!apiKey) {
-        return missingBraveKeyPayload();
-      }
-
-      const params = args as Record<string, unknown>;
-      const query = readStringParam(params, "query", { required: true });
-      const count =
-        readNumberParam(params, "count", { integer: true }) ??
-        searchConfig?.maxResults ??
-        undefined;
-      const country = readStringParam(params, "country");
-      const language = readStringParam(params, "language");
-      const search_lang = readStringParam(params, "search_lang");
-      const ui_lang = readStringParam(params, "ui_lang");
-      const normalizedLanguage = normalizeBraveLanguageParams({
-        search_lang: search_lang || language,
-        ui_lang,
-      });
-      if (normalizedLanguage.invalidField === "search_lang") {
-        return {
-          error: "invalid_search_lang",
-          message:
-            "search_lang must be a Brave-supported language code like 'en', 'en-gb', 'zh-hans', or 'zh-hant'.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      if (normalizedLanguage.invalidField === "ui_lang") {
-        return {
-          error: "invalid_ui_lang",
-          message: "ui_lang must be a language-region locale like 'en-US'.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      if (normalizedLanguage.ui_lang && braveMode === "llm-context") {
-        return {
-          error: "unsupported_ui_lang",
-          message:
-            "ui_lang is not supported by Brave llm-context mode. Remove ui_lang or use Brave web mode for locale-based UI hints.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-
-      const rawFreshness = readStringParam(params, "freshness");
-      if (rawFreshness && braveMode === "llm-context") {
-        return {
-          error: "unsupported_freshness",
-          message:
-            "freshness filtering is not supported by Brave llm-context mode. Remove freshness or use Brave web mode.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      const freshness = rawFreshness ? normalizeFreshness(rawFreshness, "brave") : undefined;
-      if (rawFreshness && !freshness) {
-        return {
-          error: "invalid_freshness",
-          message: "freshness must be day, week, month, or year.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-
-      const rawDateAfter = readStringParam(params, "date_after");
-      const rawDateBefore = readStringParam(params, "date_before");
-      if (rawFreshness && (rawDateAfter || rawDateBefore)) {
-        return {
-          error: "conflicting_time_filters",
-          message:
-            "freshness and date_after/date_before cannot be used together. Use either freshness (day/week/month/year) or a date range (date_after/date_before), not both.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      if ((rawDateAfter || rawDateBefore) && braveMode === "llm-context") {
-        return {
-          error: "unsupported_date_filter",
-          message:
-            "date_after/date_before filtering is not supported by Brave llm-context mode. Use Brave web mode for date filters.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      const dateAfter = rawDateAfter ? normalizeToIsoDate(rawDateAfter) : undefined;
-      if (rawDateAfter && !dateAfter) {
-        return {
-          error: "invalid_date",
-          message: "date_after must be YYYY-MM-DD format.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      const dateBefore = rawDateBefore ? normalizeToIsoDate(rawDateBefore) : undefined;
-      if (rawDateBefore && !dateBefore) {
-        return {
-          error: "invalid_date",
-          message: "date_before must be YYYY-MM-DD format.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-      if (dateAfter && dateBefore && dateAfter > dateBefore) {
-        return {
-          error: "invalid_date_range",
-          message: "date_after must be before date_before.",
-          docs: "https://docs.openclaw.ai/tools/web",
-        };
-      }
-
-      const cacheKey = buildSearchCacheKey([
-        "brave",
-        braveMode,
-        query,
-        resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
-        country,
-        normalizedLanguage.search_lang,
-        normalizedLanguage.ui_lang,
-        freshness,
-        dateAfter,
-        dateBefore,
-      ]);
-      const cached = readCachedSearchPayload(cacheKey);
-      if (cached) {
-        return cached;
-      }
-
-      const start = Date.now();
-      const timeoutSeconds = resolveSearchTimeoutSeconds(searchConfig);
-      const cacheTtlMs = resolveSearchCacheTtlMs(searchConfig);
-
-      if (braveMode === "llm-context") {
-        const { results, sources } = await runBraveLlmContextSearch({
-          query,
-          apiKey,
-          timeoutSeconds,
-          country: country ?? undefined,
-          search_lang: normalizedLanguage.search_lang,
-          freshness,
-        });
-        const payload = {
-          query,
-          provider: "brave",
-          mode: "llm-context" as const,
-          count: results.length,
-          tookMs: Date.now() - start,
-          externalContent: {
-            untrusted: true,
-            source: "web_search",
-            provider: "brave",
-            wrapped: true,
-          },
-          results: results.map((entry) => ({
-            title: entry.title ? wrapWebContent(entry.title, "web_search") : "",
-            url: entry.url,
-            snippets: entry.snippets.map((snippet) => wrapWebContent(snippet, "web_search")),
-            siteName: entry.siteName,
-          })),
-          sources,
-        };
-        writeCachedSearchPayload(cacheKey, payload, cacheTtlMs);
-        return payload;
-      }
-
-      const results = await runBraveWebSearch({
-        query,
-        count: resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
-        apiKey,
-        timeoutSeconds,
-        country: country ?? undefined,
-        search_lang: normalizedLanguage.search_lang,
-        ui_lang: normalizedLanguage.ui_lang,
-        freshness,
-        dateAfter,
-        dateBefore,
-      });
-      const payload = {
-        query,
-        provider: "brave",
-        count: results.length,
-        tookMs: Date.now() - start,
-        externalContent: {
-          untrusted: true,
-          source: "web_search",
-          provider: "brave",
-          wrapped: true,
-        },
-        results,
-      };
-      writeCachedSearchPayload(cacheKey, payload, cacheTtlMs);
-      return payload;
-    },
-  };
-}
-
-export function createBraveWebSearchProvider(): WebSearchProviderPlugin {
-  return {
-    id: "brave",
-    label: "Brave Search",
-    hint: "Structured results · country/language/time filters",
-    envVars: ["BRAVE_API_KEY"],
-    placeholder: "BSA...",
-    signupUrl: "https://brave.com/search/api/",
-    docsUrl: "https://docs.openclaw.ai/brave-search",
-    autoDetectOrder: 10,
-    credentialPath: "plugins.entries.brave.config.webSearch.apiKey",
-    inactiveSecretPaths: ["plugins.entries.brave.config.webSearch.apiKey"],
-    getCredentialValue: (searchConfig) => searchConfig?.apiKey,
-    setCredentialValue: (searchConfigTarget, value) => {
-      searchConfigTarget.apiKey = value;
-    },
-    getConfiguredCredentialValue: (config) =>
-      resolveProviderWebSearchPluginConfig(config, "brave")?.apiKey,
-    setConfiguredCredentialValue: (configTarget, value) => {
-      setProviderWebSearchPluginConfigValue(configTarget, "brave", "apiKey", value);
-    },
-    createTool: (ctx) =>
-      createBraveToolDefinition(ctx.config, ctx.searchConfig as SearchConfigRecord | undefined),
-  };
-}
-
-export const __testing = {
-  normalizeFreshness,
-  normalizeBraveLanguageParams,
-  resolveBraveMode,
-  mapBraveLlmContextResults,
-} as const;

extensions/chutes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/chutes-provider",
-  "version": "2026.3.14",
+  "version": "2026.3.17",
   "private": true,
   "description": "OpenClaw Chutes.ai provider plugin",
   "type": "module",

extensions/diffs/package.json

@@ -8,7 +8,7 @@
     "build:viewer": "bun build src/viewer-client.ts --target browser --format esm --minify --outfile assets/viewer-runtime.js"
   },
   "dependencies": {
-    "@pierre/diffs": "1.1.1",
+    "@pierre/diffs": "1.1.0",
     "@sinclair/typebox": "0.34.48",
     "playwright-core": "1.58.2"
   },

extensions/discord/api.ts

@@ -3,7 +3,6 @@ export * from "./src/accounts.js";
 export * from "./src/actions/handle-action.guild-admin.js";
 export * from "./src/actions/handle-action.js";
 export * from "./src/components.js";
-export * from "./src/group-policy.js";
 export * from "./src/normalize.js";
 export * from "./src/pluralkit.js";
 export * from "./src/session-key-normalization.js";

extensions/discord/runtime-api.ts

@@ -1,7 +1,4 @@
 export * from "./src/audit.js";
-export * from "./src/actions/runtime.js";
-export * from "./src/actions/runtime.moderation-shared.js";
-export * from "./src/actions/runtime.shared.js";
 export * from "./src/channel-actions.js";
 export * from "./src/directory-live.js";
 export * from "./src/monitor.js";

extensions/discord/src/account-inspect.ts

@@ -1,16 +1,18 @@
+import {
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/account-resolution";
+import {
+  hasConfiguredSecretInput,
+  normalizeSecretInputString,
+} from "openclaw/plugin-sdk/config-runtime";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/discord";
 import {
   mergeDiscordAccountConfig,
   resolveDefaultDiscordAccountId,
   resolveDiscordAccountConfig,
 } from "./accounts.js";
-import {
-  DEFAULT_ACCOUNT_ID,
-  normalizeAccountId,
-  hasConfiguredSecretInput,
-  normalizeSecretInputString,
-  type OpenClawConfig,
-  type DiscordAccountConfig,
-} from "./runtime-api.js";
 
 export type DiscordCredentialStatus = "available" | "configured_unavailable" | "missing";
 

extensions/discord/src/accounts.ts

@@ -4,9 +4,8 @@ import {
   normalizeAccountId,
   resolveAccountEntry,
   type OpenClawConfig,
-  type DiscordAccountConfig,
-  type DiscordActionConfig,
-} from "./runtime-api.js";
+} from "openclaw/plugin-sdk/account-resolution";
+import type { DiscordAccountConfig, DiscordActionConfig } from "openclaw/plugin-sdk/discord";
 import { resolveDiscordToken } from "./token.js";
 
 export type ResolvedDiscordAccount = {

extensions/discord/src/actions/handle-action.guild-admin.ts

@@ -5,12 +5,12 @@ import {
   readStringArrayParam,
   readStringParam,
 } from "openclaw/plugin-sdk/agent-runtime";
-import type { ChannelMessageActionContext } from "openclaw/plugin-sdk/channel-runtime";
-import { handleDiscordAction } from "./runtime.js";
 import {
   isDiscordModerationAction,
   readDiscordModerationCommand,
-} from "./runtime.moderation-shared.js";
+} from "openclaw/plugin-sdk/agent-runtime";
+import { handleDiscordAction } from "openclaw/plugin-sdk/agent-runtime";
+import type { ChannelMessageActionContext } from "openclaw/plugin-sdk/channel-runtime";
 
 type Ctx = Pick<
   ChannelMessageActionContext,

extensions/discord/src/actions/handle-action.ts

@@ -4,6 +4,8 @@ import {
   readStringArrayParam,
   readStringParam,
 } from "openclaw/plugin-sdk/agent-runtime";
+import { readDiscordParentIdParam } from "openclaw/plugin-sdk/agent-runtime";
+import { handleDiscordAction } from "openclaw/plugin-sdk/agent-runtime";
 import { readBooleanParam } from "openclaw/plugin-sdk/boolean-param";
 import { resolveReactionMessageId } from "openclaw/plugin-sdk/channel-runtime";
 import type { ChannelMessageActionContext } from "openclaw/plugin-sdk/channel-runtime";
@@ -11,8 +13,6 @@ import { normalizeInteractiveReply } from "openclaw/plugin-sdk/channel-runtime";
 import { buildDiscordInteractiveComponents } from "../shared-interactive.js";
 import { resolveDiscordChannelId } from "../targets.js";
 import { tryHandleDiscordMessageActionGuildAdmin } from "./handle-action.guild-admin.js";
-import { handleDiscordAction } from "./runtime.js";
-import { readDiscordParentIdParam } from "./runtime.shared.js";
 
 const providerId = "discord";
 

extensions/discord/src/channel.setup.ts

@@ -1,5 +1,5 @@
+import { type ChannelPlugin } from "openclaw/plugin-sdk/discord";
 import { type ResolvedDiscordAccount } from "./accounts.js";
-import { type ChannelPlugin } from "./runtime-api.js";
 import { discordSetupAdapter } from "./setup-core.js";
 import { createDiscordPluginBase } from "./shared.js";
 

extensions/discord/src/channel.test.ts

@@ -209,42 +209,3 @@ describe("discordPlugin outbound", () => {
     expect(runtimeMonitorDiscordProvider).not.toHaveBeenCalled();
   });
 });
-
-describe("discordPlugin groups", () => {
-  it("uses plugin-owned group policy resolvers", () => {
-    const cfg = {
-      channels: {
-        discord: {
-          token: "discord-test",
-          guilds: {
-            guild1: {
-              requireMention: false,
-              tools: { allow: ["message.guild"] },
-              channels: {
-                "123": {
-                  requireMention: true,
-                  tools: { allow: ["message.channel"] },
-                },
-              },
-            },
-          },
-        },
-      },
-    } as OpenClawConfig;
-
-    expect(
-      discordPlugin.groups?.resolveRequireMention?.({
-        cfg,
-        groupSpace: "guild1",
-        groupId: "123",
-      }),
-    ).toBe(true);
-    expect(
-      discordPlugin.groups?.resolveToolPolicy?.({
-        cfg,
-        groupSpace: "guild1",
-        groupId: "123",
-      }),
-    ).toEqual({ allow: ["message.channel"] });
-  });
-});

extensions/discord/src/channel.ts

@@ -3,14 +3,30 @@ import {
   buildAccountScopedAllowlistConfigEditor,
   resolveLegacyDmAllowlistConfigPaths,
 } from "openclaw/plugin-sdk/allowlist-config-edit";
-import { createScopedDmSecurityResolver } from "openclaw/plugin-sdk/channel-config-helpers";
 import {
+  buildAccountScopedDmSecurityPolicy,
   collectOpenGroupPolicyConfiguredRouteWarnings,
   collectOpenProviderGroupPolicyWarnings,
 } from "openclaw/plugin-sdk/channel-config-helpers";
 import { resolveOutboundSendDep } from "openclaw/plugin-sdk/channel-runtime";
 import { normalizeMessageChannel } from "openclaw/plugin-sdk/channel-runtime";
 import { buildOutboundBaseSessionKey, normalizeOutboundThreadId } from "openclaw/plugin-sdk/core";
+import {
+  buildComputedAccountStatusSnapshot,
+  buildTokenChannelStatusSummary,
+  DEFAULT_ACCOUNT_ID,
+  getChatChannelMeta,
+  listDiscordDirectoryGroupsFromConfig,
+  listDiscordDirectoryPeersFromConfig,
+  PAIRING_APPROVED_MESSAGE,
+  projectCredentialSnapshotFields,
+  resolveConfiguredFromCredentialStatuses,
+  resolveDiscordGroupRequireMention,
+  resolveDiscordGroupToolPolicy,
+  type ChannelMessageActionAdapter,
+  type ChannelPlugin,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/discord";
 import { resolveThreadSessionKeys, type RoutePeer } from "openclaw/plugin-sdk/routing";
 import {
   listDiscordAccountIds,
@@ -18,18 +34,10 @@ import {
   type ResolvedDiscordAccount,
 } from "./accounts.js";
 import { auditDiscordChannelPermissions, collectDiscordAuditChannelIds } from "./audit.js";
-import {
-  listDiscordDirectoryGroupsFromConfig,
-  listDiscordDirectoryPeersFromConfig,
-} from "./directory-config.js";
 import {
   isDiscordExecApprovalClientEnabled,
   shouldSuppressLocalDiscordExecApprovalPrompt,
 } from "./exec-approvals.js";
-import {
-  resolveDiscordGroupRequireMention,
-  resolveDiscordGroupToolPolicy,
-} from "./group-policy.js";
 import { monitorDiscordProvider } from "./monitor.js";
 import {
   looksLikeDiscordTargetId,
@@ -38,18 +46,6 @@ import {
 } from "./normalize.js";
 import { probeDiscord, type DiscordProbe } from "./probe.js";
 import { resolveDiscordUserAllowlist } from "./resolve-users.js";
-import {
-  buildComputedAccountStatusSnapshot,
-  buildTokenChannelStatusSummary,
-  type ChannelMessageActionAdapter,
-  type ChannelPlugin,
-  DEFAULT_ACCOUNT_ID,
-  getChatChannelMeta,
-  PAIRING_APPROVED_MESSAGE,
-  projectCredentialSnapshotFields,
-  resolveConfiguredFromCredentialStatuses,
-  type OpenClawConfig,
-} from "./runtime-api.js";
 import { getDiscordRuntime } from "./runtime.js";
 import { fetchChannelPermissionsDiscord } from "./send.js";
 import { discordSetupAdapter } from "./setup-core.js";
@@ -65,14 +61,6 @@ type DiscordSendFn = ReturnType<
 const meta = getChatChannelMeta("discord");
 const REQUIRED_DISCORD_PERMISSIONS = ["ViewChannel", "SendMessages"] as const;
 
-const resolveDiscordDmPolicy = createScopedDmSecurityResolver<ResolvedDiscordAccount>({
-  channelKey: "discord",
-  resolvePolicy: (account) => account.config.dm?.policy,
-  resolveAllowFrom: (account) => account.config.dm?.allowFrom,
-  allowFromPathSuffix: "dm.",
-  normalizeEntry: (raw) => raw.replace(/^(discord|user):/i, "").replace(/^<@!?(\d+)>$/, "$1"),
-});
-
 function formatDiscordIntents(intents?: {
   messageContent?: string;
   guildMembers?: string;
@@ -91,6 +79,12 @@ function formatDiscordIntents(intents?: {
 const discordMessageActions: ChannelMessageActionAdapter = {
   describeMessageTool: (ctx) =>
     getDiscordRuntime().channel.discord.messageActions?.describeMessageTool?.(ctx) ?? null,
+  listActions: (ctx) =>
+    getDiscordRuntime().channel.discord.messageActions?.listActions?.(ctx) ?? [],
+  getCapabilities: (ctx) =>
+    getDiscordRuntime().channel.discord.messageActions?.getCapabilities?.(ctx) ?? [],
+  getToolSchema: (ctx) =>
+    getDiscordRuntime().channel.discord.messageActions?.getToolSchema?.(ctx) ?? null,
   extractToolSend: (ctx) =>
     getDiscordRuntime().channel.discord.messageActions?.extractToolSend?.(ctx) ?? null,
   handleAction: async (ctx) => {
@@ -312,7 +306,18 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
     }),
   },
   security: {
-    resolveDmPolicy: resolveDiscordDmPolicy,
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      return buildAccountScopedDmSecurityPolicy({
+        cfg,
+        channelKey: "discord",
+        accountId,
+        fallbackAccountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+        policy: account.config.dm?.policy,
+        allowFrom: account.config.dm?.allowFrom ?? [],
+        allowFromPathSuffix: "dm.",
+        normalizeEntry: (raw) => raw.replace(/^(discord|user):/i, "").replace(/^<@!?(\d+)>$/, "$1"),
+      });
+    },
     collectWarnings: ({ account, cfg }) => {
       const guildEntries = account.config.guilds ?? {};
       const guildsConfigured = Object.keys(guildEntries).length > 0;
@@ -361,7 +366,6 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount> = {
   },
   messaging: {
     normalizeTarget: normalizeDiscordMessagingTarget,
-    resolveSessionTarget: ({ id }) => normalizeDiscordMessagingTarget(`channel:${id}`),
     parseExplicitTarget: ({ raw }) => parseDiscordExplicitTarget(raw),
     inferTargetChatType: ({ to }) => parseDiscordExplicitTarget(to)?.chatType,
     buildCrossContextComponents: buildDiscordCrossContextComponents,

extensions/discord/src/directory-config.ts

@@ -1,57 +0,0 @@
-import {
-  applyDirectoryQueryAndLimit,
-  collectNormalizedDirectoryIds,
-  toDirectoryEntries,
-  type DirectoryConfigParams,
-} from "openclaw/plugin-sdk/directory-runtime";
-import type { InspectedDiscordAccount } from "../../../src/channels/read-only-account-inspect.discord.runtime.js";
-import { inspectReadOnlyChannelAccount } from "../../../src/channels/read-only-account-inspect.js";
-
-export async function listDiscordDirectoryPeersFromConfig(params: DirectoryConfigParams) {
-  const account = (await inspectReadOnlyChannelAccount({
-    channelId: "discord",
-    cfg: params.cfg,
-    accountId: params.accountId,
-  })) as InspectedDiscordAccount | null;
-  if (!account || !("config" in account)) {
-    return [];
-  }
-
-  const allowFrom = account.config.allowFrom ?? account.config.dm?.allowFrom ?? [];
-  const guildUsers = Object.values(account.config.guilds ?? {}).flatMap((guild) => [
-    ...(guild.users ?? []),
-    ...Object.values(guild.channels ?? {}).flatMap((channel) => channel.users ?? []),
-  ]);
-  const ids = collectNormalizedDirectoryIds({
-    sources: [allowFrom, Object.keys(account.config.dms ?? {}), guildUsers],
-    normalizeId: (raw) => {
-      const mention = raw.match(/^<@!?(\d+)>$/);
-      const cleaned = (mention?.[1] ?? raw).replace(/^(discord|user):/i, "").trim();
-      return /^\d+$/.test(cleaned) ? `user:${cleaned}` : null;
-    },
-  });
-  return toDirectoryEntries("user", applyDirectoryQueryAndLimit(ids, params));
-}
-
-export async function listDiscordDirectoryGroupsFromConfig(params: DirectoryConfigParams) {
-  const account = (await inspectReadOnlyChannelAccount({
-    channelId: "discord",
-    cfg: params.cfg,
-    accountId: params.accountId,
-  })) as InspectedDiscordAccount | null;
-  if (!account || !("config" in account)) {
-    return [];
-  }
-
-  const ids = collectNormalizedDirectoryIds({
-    sources: Object.values(account.config.guilds ?? {}).map((guild) =>
-      Object.keys(guild.channels ?? {}),
-    ),
-    normalizeId: (raw) => {
-      const mention = raw.match(/^<#(\d+)>$/);
-      const cleaned = (mention?.[1] ?? raw).replace(/^(discord|channel|group):/i, "").trim();
-      return /^\d+$/.test(cleaned) ? `channel:${cleaned}` : null;
-    },
-  });
-  return toDirectoryEntries("group", applyDirectoryQueryAndLimit(ids, params));
-}

extensions/discord/src/directory-live.test.ts

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { DirectoryConfigParams } from "../../../src/channels/plugins/directory-config.js";
 import type { OpenClawConfig } from "../../../src/config/config.js";
-import type { DirectoryConfigParams } from "../../../src/plugin-sdk/directory-runtime.js";
 import { listDiscordDirectoryGroupsLive, listDiscordDirectoryPeersLive } from "./directory-live.js";
 
 function makeParams(overrides: Partial<DirectoryConfigParams> = {}): DirectoryConfigParams {

extensions/discord/src/group-policy.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  resolveDiscordGroupRequireMention,
-  resolveDiscordGroupToolPolicy,
-} from "./group-policy.js";
-
-describe("discord group policy", () => {
-  it("prefers channel policy, then guild policy, with sender-specific overrides", () => {
-    const discordCfg = {
-      channels: {
-        discord: {
-          token: "discord-test",
-          guilds: {
-            guild1: {
-              requireMention: false,
-              tools: { allow: ["message.guild"] },
-              toolsBySender: {
-                "id:user:guild-admin": { allow: ["sessions.list"] },
-              },
-              channels: {
-                "123": {
-                  requireMention: true,
-                  tools: { allow: ["message.channel"] },
-                  toolsBySender: {
-                    "id:user:channel-admin": { deny: ["exec"] },
-                  },
-                },
-              },
-            },
-          },
-        },
-      },
-      // oxlint-disable-next-line typescript/no-explicit-any
-    } as any;
-
-    expect(
-      resolveDiscordGroupRequireMention({ cfg: discordCfg, groupSpace: "guild1", groupId: "123" }),
-    ).toBe(true);
-    expect(
-      resolveDiscordGroupRequireMention({
-        cfg: discordCfg,
-        groupSpace: "guild1",
-        groupId: "missing",
-      }),
-    ).toBe(false);
-    expect(
-      resolveDiscordGroupToolPolicy({
-        cfg: discordCfg,
-        groupSpace: "guild1",
-        groupId: "123",
-        senderId: "user:channel-admin",
-      }),
-    ).toEqual({ deny: ["exec"] });
-    expect(
-      resolveDiscordGroupToolPolicy({
-        cfg: discordCfg,
-        groupSpace: "guild1",
-        groupId: "123",
-        senderId: "user:someone",
-      }),
-    ).toEqual({ allow: ["message.channel"] });
-    expect(
-      resolveDiscordGroupToolPolicy({
-        cfg: discordCfg,
-        groupSpace: "guild1",
-        groupId: "missing",
-        senderId: "user:guild-admin",
-      }),
-    ).toEqual({ allow: ["sessions.list"] });
-    expect(
-      resolveDiscordGroupToolPolicy({
-        cfg: discordCfg,
-        groupSpace: "guild1",
-        groupId: "missing",
-        senderId: "user:someone",
-      }),
-    ).toEqual({ allow: ["message.guild"] });
-  });
-});

extensions/discord/src/group-policy.ts

@@ -1,111 +0,0 @@
-import {
-  resolveToolsBySender,
-  type GroupToolPolicyBySenderConfig,
-  type GroupToolPolicyConfig,
-} from "openclaw/plugin-sdk/channel-policy";
-import { type ChannelGroupContext } from "openclaw/plugin-sdk/channel-runtime";
-import { normalizeAtHashSlug } from "openclaw/plugin-sdk/core";
-import type { DiscordConfig } from "openclaw/plugin-sdk/discord";
-
-function normalizeDiscordSlug(value?: string | null) {
-  return normalizeAtHashSlug(value);
-}
-
-type SenderScopedToolsEntry = {
-  tools?: GroupToolPolicyConfig;
-  toolsBySender?: GroupToolPolicyBySenderConfig;
-  requireMention?: boolean;
-};
-
-function resolveDiscordGuildEntry(guilds: DiscordConfig["guilds"], groupSpace?: string | null) {
-  if (!guilds || Object.keys(guilds).length === 0) {
-    return null;
-  }
-  const space = groupSpace?.trim() ?? "";
-  if (space && guilds[space]) {
-    return guilds[space];
-  }
-  const normalized = normalizeDiscordSlug(space);
-  if (normalized && guilds[normalized]) {
-    return guilds[normalized];
-  }
-  if (normalized) {
-    const match = Object.values(guilds).find(
-      (entry) => normalizeDiscordSlug(entry?.slug ?? undefined) === normalized,
-    );
-    if (match) {
-      return match;
-    }
-  }
-  return guilds["*"] ?? null;
-}
-
-function resolveDiscordChannelEntry<TEntry extends SenderScopedToolsEntry>(
-  channelEntries: Record<string, TEntry> | undefined,
-  params: { groupId?: string | null; groupChannel?: string | null },
-): TEntry | undefined {
-  if (!channelEntries || Object.keys(channelEntries).length === 0) {
-    return undefined;
-  }
-  const groupChannel = params.groupChannel;
-  const channelSlug = normalizeDiscordSlug(groupChannel);
-  return (
-    (params.groupId ? channelEntries[params.groupId] : undefined) ??
-    (channelSlug
-      ? (channelEntries[channelSlug] ?? channelEntries[`#${channelSlug}`])
-      : undefined) ??
-    (groupChannel ? channelEntries[normalizeDiscordSlug(groupChannel)] : undefined)
-  );
-}
-
-function resolveSenderToolsEntry(
-  entry: SenderScopedToolsEntry | undefined | null,
-  params: ChannelGroupContext,
-): GroupToolPolicyConfig | undefined {
-  if (!entry) {
-    return undefined;
-  }
-  const senderPolicy = resolveToolsBySender({
-    toolsBySender: entry.toolsBySender,
-    senderId: params.senderId,
-    senderName: params.senderName,
-    senderUsername: params.senderUsername,
-    senderE164: params.senderE164,
-  });
-  return senderPolicy ?? entry.tools;
-}
-
-function resolveDiscordPolicyContext(params: ChannelGroupContext) {
-  const guildEntry = resolveDiscordGuildEntry(
-    params.cfg.channels?.discord?.guilds,
-    params.groupSpace,
-  );
-  const channelEntries = guildEntry?.channels;
-  const channelEntry =
-    channelEntries && Object.keys(channelEntries).length > 0
-      ? resolveDiscordChannelEntry(channelEntries, params)
-      : undefined;
-  return { guildEntry, channelEntry };
-}
-
-export function resolveDiscordGroupRequireMention(params: ChannelGroupContext): boolean {
-  const context = resolveDiscordPolicyContext(params);
-  if (typeof context.channelEntry?.requireMention === "boolean") {
-    return context.channelEntry.requireMention;
-  }
-  if (typeof context.guildEntry?.requireMention === "boolean") {
-    return context.guildEntry.requireMention;
-  }
-  return true;
-}
-
-export function resolveDiscordGroupToolPolicy(
-  params: ChannelGroupContext,
-): GroupToolPolicyConfig | undefined {
-  const context = resolveDiscordPolicyContext(params);
-  const channelPolicy = resolveSenderToolsEntry(context.channelEntry, params);
-  if (channelPolicy) {
-    return channelPolicy;
-  }
-  return resolveSenderToolsEntry(context.guildEntry, params);
-}

extensions/discord/src/monitor/agent-components-helpers.ts

@@ -1,754 +0,0 @@
-import {
-  type ButtonInteraction,
-  type ChannelSelectMenuInteraction,
-  type ComponentData,
-  type MentionableSelectMenuInteraction,
-  type ModalInteraction,
-  type RoleSelectMenuInteraction,
-  type StringSelectMenuInteraction,
-  type UserSelectMenuInteraction,
-} from "@buape/carbon";
-import type { APIStringSelectComponent } from "discord-api-types/v10";
-import { ChannelType } from "discord-api-types/v10";
-import { resolveCommandAuthorizedFromAuthorizers } from "openclaw/plugin-sdk/channel-runtime";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
-import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-runtime";
-import { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/config-runtime";
-import {
-  issuePairingChallenge,
-  upsertChannelPairingRequest,
-} from "openclaw/plugin-sdk/conversation-runtime";
-import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
-import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
-import {
-  readStoreAllowFromForDmPolicy,
-  resolvePinnedMainDmOwnerFromAllowlist,
-} from "openclaw/plugin-sdk/security-runtime";
-import { logError } from "openclaw/plugin-sdk/text-runtime";
-import {
-  createDiscordFormModal,
-  parseDiscordComponentCustomId,
-  parseDiscordModalCustomId,
-  type DiscordComponentEntry,
-  type DiscordModalEntry,
-} from "../components.js";
-import {
-  type DiscordGuildEntryResolved,
-  normalizeDiscordAllowList,
-  normalizeDiscordSlug,
-  resolveDiscordAllowListMatch,
-  resolveDiscordChannelConfigWithFallback,
-  resolveDiscordGuildEntry,
-  resolveDiscordMemberAccessState,
-  resolveDiscordOwnerAccess,
-} from "./allow-list.js";
-import { formatDiscordUserTag } from "./format.js";
-
-export const AGENT_BUTTON_KEY = "agent";
-export const AGENT_SELECT_KEY = "agentsel";
-
-export type DiscordUser = Parameters<typeof formatDiscordUserTag>[0];
-
-export type AgentComponentMessageInteraction =
-  | ButtonInteraction
-  | StringSelectMenuInteraction
-  | RoleSelectMenuInteraction
-  | UserSelectMenuInteraction
-  | MentionableSelectMenuInteraction
-  | ChannelSelectMenuInteraction;
-
-export type AgentComponentInteraction = AgentComponentMessageInteraction | ModalInteraction;
-
-export type DiscordChannelContext = {
-  channelName: string | undefined;
-  channelSlug: string;
-  channelType: number | undefined;
-  isThread: boolean;
-  parentId: string | undefined;
-  parentName: string | undefined;
-  parentSlug: string;
-};
-
-export type AgentComponentContext = {
-  cfg: OpenClawConfig;
-  accountId: string;
-  discordConfig?: DiscordAccountConfig;
-  runtime?: import("openclaw/plugin-sdk/runtime-env").RuntimeEnv;
-  token?: string;
-  guildEntries?: Record<string, DiscordGuildEntryResolved>;
-  allowFrom?: string[];
-  dmPolicy?: "open" | "pairing" | "allowlist" | "disabled";
-};
-
-export type ComponentInteractionContext = NonNullable<
-  Awaited<ReturnType<typeof resolveComponentInteractionContext>>
->;
-
-function formatUsername(user: { username: string; discriminator?: string | null }): string {
-  if (user.discriminator && user.discriminator !== "0") {
-    return `${user.username}#${user.discriminator}`;
-  }
-  return user.username;
-}
-
-function isThreadChannelType(channelType: number | undefined): boolean {
-  return (
-    channelType === ChannelType.PublicThread ||
-    channelType === ChannelType.PrivateThread ||
-    channelType === ChannelType.AnnouncementThread
-  );
-}
-
-function readParsedComponentId(data: ComponentData): unknown {
-  if (!data || typeof data !== "object") {
-    return undefined;
-  }
-  return "cid" in data
-    ? (data as Record<string, unknown>).cid
-    : (data as Record<string, unknown>).componentId;
-}
-
-function normalizeComponentId(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    return trimmed ? trimmed : undefined;
-  }
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return String(value);
-  }
-  return undefined;
-}
-
-function mapOptionLabels(
-  options: Array<{ value: string; label: string }> | undefined,
-  values: string[],
-) {
-  if (!options || options.length === 0) {
-    return values;
-  }
-  const map = new Map(options.map((option) => [option.value, option.label]));
-  return values.map((value) => map.get(value) ?? value);
-}
-
-/**
- * The component custom id only carries the logical button id. Channel binding
- * comes from Discord's trusted interaction payload.
- */
-export function buildAgentButtonCustomId(componentId: string): string {
-  return `${AGENT_BUTTON_KEY}:componentId=${encodeURIComponent(componentId)}`;
-}
-
-export function buildAgentSelectCustomId(componentId: string): string {
-  return `${AGENT_SELECT_KEY}:componentId=${encodeURIComponent(componentId)}`;
-}
-
-export function resolveAgentComponentRoute(params: {
-  ctx: AgentComponentContext;
-  rawGuildId: string | undefined;
-  memberRoleIds: string[];
-  isDirectMessage: boolean;
-  userId: string;
-  channelId: string;
-  parentId: string | undefined;
-}) {
-  return resolveAgentRoute({
-    cfg: params.ctx.cfg,
-    channel: "discord",
-    accountId: params.ctx.accountId,
-    guildId: params.rawGuildId,
-    memberRoleIds: params.memberRoleIds,
-    peer: {
-      kind: params.isDirectMessage ? "direct" : "channel",
-      id: params.isDirectMessage ? params.userId : params.channelId,
-    },
-    parentPeer: params.parentId ? { kind: "channel", id: params.parentId } : undefined,
-  });
-}
-
-export async function ackComponentInteraction(params: {
-  interaction: AgentComponentInteraction;
-  replyOpts: { ephemeral?: boolean };
-  label: string;
-}) {
-  try {
-    await params.interaction.reply({
-      content: "✓",
-      ...params.replyOpts,
-    });
-  } catch (err) {
-    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
-  }
-}
-
-export function resolveDiscordChannelContext(
-  interaction: AgentComponentInteraction,
-): DiscordChannelContext {
-  const channel = interaction.channel;
-  const channelName = channel && "name" in channel ? (channel.name as string) : undefined;
-  const channelSlug = channelName ? normalizeDiscordSlug(channelName) : "";
-  const channelType = channel && "type" in channel ? (channel.type as number) : undefined;
-  const isThread = isThreadChannelType(channelType);
-
-  let parentId: string | undefined;
-  let parentName: string | undefined;
-  let parentSlug = "";
-  if (isThread && channel && "parentId" in channel) {
-    parentId = (channel.parentId as string) ?? undefined;
-    if ("parent" in channel) {
-      const parent = (channel as { parent?: { name?: string } }).parent;
-      if (parent?.name) {
-        parentName = parent.name;
-        parentSlug = normalizeDiscordSlug(parentName);
-      }
-    }
-  }
-
-  return { channelName, channelSlug, channelType, isThread, parentId, parentName, parentSlug };
-}
-
-export async function resolveComponentInteractionContext(params: {
-  interaction: AgentComponentInteraction;
-  label: string;
-  defer?: boolean;
-}) {
-  const { interaction, label } = params;
-  const channelId = interaction.rawData.channel_id;
-  if (!channelId) {
-    logError(`${label}: missing channel_id in interaction`);
-    return null;
-  }
-
-  const user = interaction.user;
-  if (!user) {
-    logError(`${label}: missing user in interaction`);
-    return null;
-  }
-
-  const shouldDefer = params.defer !== false && "defer" in interaction;
-  let didDefer = false;
-  if (shouldDefer) {
-    try {
-      await (interaction as AgentComponentMessageInteraction).defer({ ephemeral: true });
-      didDefer = true;
-    } catch (err) {
-      logError(`${label}: failed to defer interaction: ${String(err)}`);
-    }
-  }
-  const replyOpts = didDefer ? {} : { ephemeral: true };
-
-  const username = formatUsername(user);
-  const userId = user.id;
-  const rawGuildId = interaction.rawData.guild_id;
-  const isDirectMessage = !rawGuildId;
-  const memberRoleIds = Array.isArray(interaction.rawData.member?.roles)
-    ? interaction.rawData.member.roles.map((roleId: string) => String(roleId))
-    : [];
-
-  return {
-    channelId,
-    user,
-    username,
-    userId,
-    replyOpts,
-    rawGuildId,
-    isDirectMessage,
-    memberRoleIds,
-  };
-}
-
-export async function ensureGuildComponentMemberAllowed(params: {
-  interaction: AgentComponentInteraction;
-  guildInfo: ReturnType<typeof resolveDiscordGuildEntry>;
-  channelId: string;
-  rawGuildId: string | undefined;
-  channelCtx: DiscordChannelContext;
-  memberRoleIds: string[];
-  user: DiscordUser;
-  replyOpts: { ephemeral?: boolean };
-  componentLabel: string;
-  unauthorizedReply: string;
-  allowNameMatching: boolean;
-}) {
-  const {
-    interaction,
-    guildInfo,
-    channelId,
-    rawGuildId,
-    channelCtx,
-    memberRoleIds,
-    user,
-    replyOpts,
-    componentLabel,
-    unauthorizedReply,
-  } = params;
-
-  if (!rawGuildId) {
-    return true;
-  }
-
-  const channelConfig = resolveDiscordChannelConfigWithFallback({
-    guildInfo,
-    channelId,
-    channelName: channelCtx.channelName,
-    channelSlug: channelCtx.channelSlug,
-    parentId: channelCtx.parentId,
-    parentName: channelCtx.parentName,
-    parentSlug: channelCtx.parentSlug,
-    scope: channelCtx.isThread ? "thread" : "channel",
-  });
-
-  const { memberAllowed } = resolveDiscordMemberAccessState({
-    channelConfig,
-    guildInfo,
-    memberRoleIds,
-    sender: {
-      id: user.id,
-      name: user.username,
-      tag: user.discriminator ? `${user.username}#${user.discriminator}` : undefined,
-    },
-    allowNameMatching: params.allowNameMatching,
-  });
-  if (memberAllowed) {
-    return true;
-  }
-
-  logVerbose(`agent ${componentLabel}: blocked user ${user.id} (not in users/roles allowlist)`);
-  try {
-    await interaction.reply({
-      content: unauthorizedReply,
-      ...replyOpts,
-    });
-  } catch {}
-  return false;
-}
-
-export async function ensureComponentUserAllowed(params: {
-  entry: DiscordComponentEntry;
-  interaction: AgentComponentInteraction;
-  user: DiscordUser;
-  replyOpts: { ephemeral?: boolean };
-  componentLabel: string;
-  unauthorizedReply: string;
-  allowNameMatching: boolean;
-}) {
-  const allowList = normalizeDiscordAllowList(params.entry.allowedUsers, [
-    "discord:",
-    "user:",
-    "pk:",
-  ]);
-  if (!allowList) {
-    return true;
-  }
-  const match = resolveDiscordAllowListMatch({
-    allowList,
-    candidate: {
-      id: params.user.id,
-      name: params.user.username,
-      tag: formatDiscordUserTag(params.user),
-    },
-    allowNameMatching: params.allowNameMatching,
-  });
-  if (match.allowed) {
-    return true;
-  }
-
-  logVerbose(
-    `discord component ${params.componentLabel}: blocked user ${params.user.id} (not in allowedUsers)`,
-  );
-  try {
-    await params.interaction.reply({
-      content: params.unauthorizedReply,
-      ...params.replyOpts,
-    });
-  } catch {}
-  return false;
-}
-
-export async function ensureAgentComponentInteractionAllowed(params: {
-  ctx: AgentComponentContext;
-  interaction: AgentComponentInteraction;
-  channelId: string;
-  rawGuildId: string | undefined;
-  memberRoleIds: string[];
-  user: DiscordUser;
-  replyOpts: { ephemeral?: boolean };
-  componentLabel: string;
-  unauthorizedReply: string;
-}) {
-  const guildInfo = resolveDiscordGuildEntry({
-    guild: params.interaction.guild ?? undefined,
-    guildId: params.rawGuildId,
-    guildEntries: params.ctx.guildEntries,
-  });
-  const channelCtx = resolveDiscordChannelContext(params.interaction);
-  const memberAllowed = await ensureGuildComponentMemberAllowed({
-    interaction: params.interaction,
-    guildInfo,
-    channelId: params.channelId,
-    rawGuildId: params.rawGuildId,
-    channelCtx,
-    memberRoleIds: params.memberRoleIds,
-    user: params.user,
-    replyOpts: params.replyOpts,
-    componentLabel: params.componentLabel,
-    unauthorizedReply: params.unauthorizedReply,
-    allowNameMatching: isDangerousNameMatchingEnabled(params.ctx.discordConfig),
-  });
-  if (!memberAllowed) {
-    return null;
-  }
-  return { parentId: channelCtx.parentId };
-}
-
-export function parseAgentComponentData(data: ComponentData): { componentId: string } | null {
-  const raw = readParsedComponentId(data);
-  const decodeSafe = (value: string): string => {
-    if (!value.includes("%")) {
-      return value;
-    }
-    if (!/%[0-9A-Fa-f]{2}/.test(value)) {
-      return value;
-    }
-    try {
-      return decodeURIComponent(value);
-    } catch {
-      return value;
-    }
-  };
-  const componentId =
-    typeof raw === "string" ? decodeSafe(raw) : typeof raw === "number" ? String(raw) : null;
-  if (!componentId) {
-    return null;
-  }
-  return { componentId };
-}
-
-async function ensureDmComponentAuthorized(params: {
-  ctx: AgentComponentContext;
-  interaction: AgentComponentInteraction;
-  user: DiscordUser;
-  componentLabel: string;
-  replyOpts: { ephemeral?: boolean };
-}) {
-  const { ctx, interaction, user, componentLabel, replyOpts } = params;
-  const dmPolicy = ctx.dmPolicy ?? "pairing";
-  if (dmPolicy === "disabled") {
-    logVerbose(`agent ${componentLabel}: blocked (DM policy disabled)`);
-    try {
-      await interaction.reply({
-        content: "DM interactions are disabled.",
-        ...replyOpts,
-      });
-    } catch {}
-    return false;
-  }
-  if (dmPolicy === "open") {
-    return true;
-  }
-
-  const storeAllowFrom = await readStoreAllowFromForDmPolicy({
-    provider: "discord",
-    accountId: ctx.accountId,
-    dmPolicy,
-  });
-  const effectiveAllowFrom = [...(ctx.allowFrom ?? []), ...storeAllowFrom];
-  const allowList = normalizeDiscordAllowList(effectiveAllowFrom, ["discord:", "user:", "pk:"]);
-  const allowMatch = allowList
-    ? resolveDiscordAllowListMatch({
-        allowList,
-        candidate: {
-          id: user.id,
-          name: user.username,
-          tag: formatDiscordUserTag(user),
-        },
-        allowNameMatching: isDangerousNameMatchingEnabled(ctx.discordConfig),
-      })
-    : { allowed: false };
-  if (allowMatch.allowed) {
-    return true;
-  }
-
-  if (dmPolicy === "pairing") {
-    const pairingResult = await issuePairingChallenge({
-      channel: "discord",
-      senderId: user.id,
-      senderIdLine: `Your Discord user id: ${user.id}`,
-      meta: {
-        tag: formatDiscordUserTag(user),
-        name: user.username,
-      },
-      upsertPairingRequest: async ({ id, meta }) =>
-        await upsertChannelPairingRequest({
-          channel: "discord",
-          id,
-          accountId: ctx.accountId,
-          meta,
-        }),
-      sendPairingReply: async (text) => {
-        await interaction.reply({
-          content: text,
-          ...replyOpts,
-        });
-      },
-    });
-    if (!pairingResult.created) {
-      try {
-        await interaction.reply({
-          content: "Pairing already requested. Ask the bot owner to approve your code.",
-          ...replyOpts,
-        });
-      } catch {}
-    }
-    return false;
-  }
-
-  logVerbose(`agent ${componentLabel}: blocked DM user ${user.id} (not in allowFrom)`);
-  try {
-    await interaction.reply({
-      content: `You are not authorized to use this ${componentLabel}.`,
-      ...replyOpts,
-    });
-  } catch {}
-  return false;
-}
-
-export async function resolveInteractionContextWithDmAuth(params: {
-  ctx: AgentComponentContext;
-  interaction: AgentComponentInteraction;
-  label: string;
-  componentLabel: string;
-  defer?: boolean;
-}) {
-  const interactionCtx = await resolveComponentInteractionContext({
-    interaction: params.interaction,
-    label: params.label,
-    defer: params.defer,
-  });
-  if (!interactionCtx) {
-    return null;
-  }
-  if (interactionCtx.isDirectMessage) {
-    const authorized = await ensureDmComponentAuthorized({
-      ctx: params.ctx,
-      interaction: params.interaction,
-      user: interactionCtx.user,
-      componentLabel: params.componentLabel,
-      replyOpts: interactionCtx.replyOpts,
-    });
-    if (!authorized) {
-      return null;
-    }
-  }
-  return interactionCtx;
-}
-
-export function parseDiscordComponentData(
-  data: ComponentData,
-  customId?: string,
-): { componentId: string; modalId?: string } | null {
-  if (!data || typeof data !== "object") {
-    return null;
-  }
-  const rawComponentId = readParsedComponentId(data);
-  const rawModalId =
-    "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
-  let componentId = normalizeComponentId(rawComponentId);
-  let modalId = normalizeComponentId(rawModalId);
-  if (!componentId && customId) {
-    const parsed = parseDiscordComponentCustomId(customId);
-    if (parsed) {
-      componentId = parsed.componentId;
-      modalId = parsed.modalId;
-    }
-  }
-  if (!componentId) {
-    return null;
-  }
-  return { componentId, modalId };
-}
-
-export function parseDiscordModalId(data: ComponentData, customId?: string): string | null {
-  if (data && typeof data === "object") {
-    const rawModalId =
-      "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
-    const modalId = normalizeComponentId(rawModalId);
-    if (modalId) {
-      return modalId;
-    }
-  }
-  if (customId) {
-    return parseDiscordModalCustomId(customId);
-  }
-  return null;
-}
-
-export function resolveInteractionCustomId(
-  interaction: AgentComponentInteraction,
-): string | undefined {
-  if (!interaction?.rawData || typeof interaction.rawData !== "object") {
-    return undefined;
-  }
-  if (!("data" in interaction.rawData)) {
-    return undefined;
-  }
-  const data = (interaction.rawData as { data?: { custom_id?: unknown } }).data;
-  const customId = data?.custom_id;
-  if (typeof customId !== "string") {
-    return undefined;
-  }
-  const trimmed = customId.trim();
-  return trimmed ? trimmed : undefined;
-}
-
-export function mapSelectValues(entry: DiscordComponentEntry, values: string[]): string[] {
-  if (entry.selectType === "string") {
-    return mapOptionLabels(entry.options, values);
-  }
-  if (entry.selectType === "user") {
-    return values.map((value) => `user:${value}`);
-  }
-  if (entry.selectType === "role") {
-    return values.map((value) => `role:${value}`);
-  }
-  if (entry.selectType === "mentionable") {
-    return values.map((value) => `mentionable:${value}`);
-  }
-  if (entry.selectType === "channel") {
-    return values.map((value) => `channel:${value}`);
-  }
-  return values;
-}
-
-export function resolveModalFieldValues(
-  field: DiscordModalEntry["fields"][number],
-  interaction: ModalInteraction,
-): string[] {
-  const fields = interaction.fields;
-  const optionLabels = field.options?.map((option) => ({
-    value: option.value,
-    label: option.label,
-  }));
-  const required = field.required === true;
-  try {
-    switch (field.type) {
-      case "text": {
-        const value = required ? fields.getText(field.id, true) : fields.getText(field.id);
-        return value ? [value] : [];
-      }
-      case "select":
-      case "checkbox":
-      case "radio": {
-        const values = required
-          ? fields.getStringSelect(field.id, true)
-          : (fields.getStringSelect(field.id) ?? []);
-        return mapOptionLabels(optionLabels, values);
-      }
-      case "role-select": {
-        try {
-          const roles = required
-            ? fields.getRoleSelect(field.id, true)
-            : (fields.getRoleSelect(field.id) ?? []);
-          return roles.map((role) => role.name ?? role.id);
-        } catch {
-          const values = required
-            ? fields.getStringSelect(field.id, true)
-            : (fields.getStringSelect(field.id) ?? []);
-          return values;
-        }
-      }
-      case "user-select": {
-        const users = required
-          ? fields.getUserSelect(field.id, true)
-          : (fields.getUserSelect(field.id) ?? []);
-        return users.map((user) => formatDiscordUserTag(user));
-      }
-      default:
-        return [];
-    }
-  } catch (err) {
-    logError(`agent modal: failed to read field ${field.id}: ${String(err)}`);
-    return [];
-  }
-}
-
-export function formatModalSubmissionText(
-  entry: DiscordModalEntry,
-  interaction: ModalInteraction,
-): string {
-  const lines: string[] = [`Form "${entry.title}" submitted.`];
-  for (const field of entry.fields) {
-    const values = resolveModalFieldValues(field, interaction);
-    if (values.length === 0) {
-      continue;
-    }
-    lines.push(`- ${field.label}: ${values.join(", ")}`);
-  }
-  if (lines.length === 1) {
-    lines.push("- (no values)");
-  }
-  return lines.join("\n");
-}
-
-export function resolveDiscordInteractionId(interaction: AgentComponentInteraction): string {
-  const rawId =
-    interaction.rawData && typeof interaction.rawData === "object" && "id" in interaction.rawData
-      ? (interaction.rawData as { id?: unknown }).id
-      : undefined;
-  if (typeof rawId === "string" && rawId.trim()) {
-    return rawId.trim();
-  }
-  if (typeof rawId === "number" && Number.isFinite(rawId)) {
-    return String(rawId);
-  }
-  return `discord-interaction:${Date.now()}`;
-}
-
-export function resolveComponentCommandAuthorized(params: {
-  ctx: AgentComponentContext;
-  interactionCtx: ComponentInteractionContext;
-  channelConfig: ReturnType<typeof resolveDiscordChannelConfigWithFallback>;
-  guildInfo: ReturnType<typeof resolveDiscordGuildEntry>;
-  allowNameMatching: boolean;
-}) {
-  const { ctx, interactionCtx, channelConfig, guildInfo } = params;
-  if (interactionCtx.isDirectMessage) {
-    return true;
-  }
-
-  const { ownerAllowList, ownerAllowed: ownerOk } = resolveDiscordOwnerAccess({
-    allowFrom: ctx.allowFrom,
-    sender: {
-      id: interactionCtx.user.id,
-      name: interactionCtx.user.username,
-      tag: formatDiscordUserTag(interactionCtx.user),
-    },
-    allowNameMatching: params.allowNameMatching,
-  });
-
-  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
-    channelConfig,
-    guildInfo,
-    memberRoleIds: interactionCtx.memberRoleIds,
-    sender: {
-      id: interactionCtx.user.id,
-      name: interactionCtx.user.username,
-      tag: formatDiscordUserTag(interactionCtx.user),
-    },
-    allowNameMatching: params.allowNameMatching,
-  });
-  const useAccessGroups = ctx.cfg.commands?.useAccessGroups !== false;
-  const authorizers = useAccessGroups
-    ? [
-        { configured: ownerAllowList != null, allowed: ownerOk },
-        { configured: hasAccessRestrictions, allowed: memberAllowed },
-      ]
-    : [{ configured: hasAccessRestrictions, allowed: memberAllowed }];
-
-  return resolveCommandAuthorizedFromAuthorizers({
-    useAccessGroups,
-    authorizers,
-    modeWhenAccessGroupsOff: "configured",
-  });
-}
-
-export { resolveDiscordGuildEntry, resolvePinnedMainDmOwnerFromAllowlist };

extensions/discord/src/monitor/agent-components.ts

@@ -19,6 +19,7 @@ import {
 import type { APIStringSelectComponent } from "discord-api-types/v10";
 import { ButtonStyle, ChannelType } from "discord-api-types/v10";
 import { resolveHumanDelayConfig } from "openclaw/plugin-sdk/agent-runtime";
+import { resolveCommandAuthorizedFromAuthorizers } from "openclaw/plugin-sdk/channel-runtime";
 import { createReplyPrefixOptions } from "openclaw/plugin-sdk/channel-runtime";
 import { recordInboundSession } from "openclaw/plugin-sdk/channel-runtime";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
@@ -26,6 +27,8 @@ import { isDangerousNameMatchingEnabled } from "openclaw/plugin-sdk/config-runti
 import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/config-runtime";
 import { readSessionUpdatedAt, resolveStorePath } from "openclaw/plugin-sdk/config-runtime";
 import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-runtime";
+import { issuePairingChallenge } from "openclaw/plugin-sdk/conversation-runtime";
+import { upsertChannelPairingRequest } from "openclaw/plugin-sdk/conversation-runtime";
 import {
   buildPluginBindingResolvedText,
   parsePluginBindingApprovalCustomId,
@@ -45,51 +48,32 @@ import { createReplyReferencePlanner } from "openclaw/plugin-sdk/reply-runtime";
 import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
 import { logVerbose } from "openclaw/plugin-sdk/runtime-env";
 import { createNonExitingRuntime, type RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import {
+  readStoreAllowFromForDmPolicy,
+  resolvePinnedMainDmOwnerFromAllowlist,
+} from "openclaw/plugin-sdk/security-runtime";
 import { logDebug, logError } from "openclaw/plugin-sdk/text-runtime";
 import { resolveDiscordMaxLinesPerMessage } from "../accounts.js";
 import { resolveDiscordComponentEntry, resolveDiscordModalEntry } from "../components-registry.js";
 import {
   createDiscordFormModal,
   formatDiscordComponentEventText,
+  parseDiscordComponentCustomId,
   parseDiscordComponentCustomIdForCarbon,
+  parseDiscordModalCustomId,
   parseDiscordModalCustomIdForCarbon,
   type DiscordComponentEntry,
   type DiscordModalEntry,
 } from "../components.js";
-import {
-  AGENT_BUTTON_KEY,
-  AGENT_SELECT_KEY,
-  ackComponentInteraction,
-  buildAgentButtonCustomId,
-  buildAgentSelectCustomId,
-  type AgentComponentContext,
-  type AgentComponentInteraction,
-  type AgentComponentMessageInteraction,
-  ensureAgentComponentInteractionAllowed,
-  ensureComponentUserAllowed,
-  ensureGuildComponentMemberAllowed,
-  formatModalSubmissionText,
-  mapSelectValues,
-  parseAgentComponentData,
-  parseDiscordComponentData,
-  parseDiscordModalId,
-  resolveAgentComponentRoute,
-  resolveComponentCommandAuthorized,
-  type ComponentInteractionContext,
-  resolveDiscordChannelContext,
-  type DiscordChannelContext,
-  resolveDiscordInteractionId,
-  resolveInteractionContextWithDmAuth,
-  resolveInteractionCustomId,
-  resolveModalFieldValues,
-  resolvePinnedMainDmOwnerFromAllowlist,
-  type DiscordUser,
-} from "./agent-components-helpers.js";
 import {
   type DiscordGuildEntryResolved,
   normalizeDiscordAllowList,
+  normalizeDiscordSlug,
+  resolveDiscordAllowListMatch,
   resolveDiscordChannelConfigWithFallback,
   resolveDiscordGuildEntry,
+  resolveDiscordMemberAccessState,
+  resolveDiscordOwnerAccess,
 } from "./allow-list.js";
 import { formatDiscordUserTag } from "./format.js";
 import {
@@ -100,6 +84,714 @@ import { buildDirectLabel, buildGuildLabel } from "./reply-context.js";
 import { deliverDiscordReply } from "./reply-delivery.js";
 import { sendTyping } from "./typing.js";
 
+const AGENT_BUTTON_KEY = "agent";
+const AGENT_SELECT_KEY = "agentsel";
+
+type DiscordUser = Parameters<typeof formatDiscordUserTag>[0];
+
+type AgentComponentMessageInteraction =
+  | ButtonInteraction
+  | StringSelectMenuInteraction
+  | RoleSelectMenuInteraction
+  | UserSelectMenuInteraction
+  | MentionableSelectMenuInteraction
+  | ChannelSelectMenuInteraction;
+
+type AgentComponentInteraction = AgentComponentMessageInteraction | ModalInteraction;
+
+type ComponentInteractionContext = NonNullable<
+  Awaited<ReturnType<typeof resolveComponentInteractionContext>>
+>;
+
+type DiscordChannelContext = {
+  channelName: string | undefined;
+  channelSlug: string;
+  channelType: number | undefined;
+  isThread: boolean;
+  parentId: string | undefined;
+  parentName: string | undefined;
+  parentSlug: string;
+};
+
+function resolveAgentComponentRoute(params: {
+  ctx: AgentComponentContext;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  isDirectMessage: boolean;
+  userId: string;
+  channelId: string;
+  parentId: string | undefined;
+}) {
+  return resolveAgentRoute({
+    cfg: params.ctx.cfg,
+    channel: "discord",
+    accountId: params.ctx.accountId,
+    guildId: params.rawGuildId,
+    memberRoleIds: params.memberRoleIds,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : "channel",
+      id: params.isDirectMessage ? params.userId : params.channelId,
+    },
+    parentPeer: params.parentId ? { kind: "channel", id: params.parentId } : undefined,
+  });
+}
+
+async function ackComponentInteraction(params: {
+  interaction: AgentComponentInteraction;
+  replyOpts: { ephemeral?: boolean };
+  label: string;
+}) {
+  try {
+    await params.interaction.reply({
+      content: "✓",
+      ...params.replyOpts,
+    });
+  } catch (err) {
+    logError(`${params.label}: failed to acknowledge interaction: ${String(err)}`);
+  }
+}
+
+function resolveDiscordChannelContext(
+  interaction: AgentComponentInteraction,
+): DiscordChannelContext {
+  const channel = interaction.channel;
+  const channelName = channel && "name" in channel ? (channel.name as string) : undefined;
+  const channelSlug = channelName ? normalizeDiscordSlug(channelName) : "";
+  const channelType = channel && "type" in channel ? (channel.type as number) : undefined;
+  const isThread = isThreadChannelType(channelType);
+
+  let parentId: string | undefined;
+  let parentName: string | undefined;
+  let parentSlug = "";
+  if (isThread && channel && "parentId" in channel) {
+    parentId = (channel.parentId as string) ?? undefined;
+    if ("parent" in channel) {
+      const parent = (channel as { parent?: { name?: string } }).parent;
+      if (parent?.name) {
+        parentName = parent.name;
+        parentSlug = normalizeDiscordSlug(parentName);
+      }
+    }
+  }
+
+  return { channelName, channelSlug, channelType, isThread, parentId, parentName, parentSlug };
+}
+
+async function resolveComponentInteractionContext(params: {
+  interaction: AgentComponentInteraction;
+  label: string;
+  defer?: boolean;
+}): Promise<{
+  channelId: string;
+  user: DiscordUser;
+  username: string;
+  userId: string;
+  replyOpts: { ephemeral?: boolean };
+  rawGuildId: string | undefined;
+  isDirectMessage: boolean;
+  memberRoleIds: string[];
+} | null> {
+  const { interaction, label } = params;
+
+  // Use interaction's actual channel_id (trusted source from Discord)
+  // This prevents channel spoofing attacks
+  const channelId = interaction.rawData.channel_id;
+  if (!channelId) {
+    logError(`${label}: missing channel_id in interaction`);
+    return null;
+  }
+
+  const user = interaction.user;
+  if (!user) {
+    logError(`${label}: missing user in interaction`);
+    return null;
+  }
+
+  const shouldDefer = params.defer !== false && "defer" in interaction;
+  let didDefer = false;
+  // Defer immediately to satisfy Discord's 3-second interaction ACK requirement.
+  // We use an ephemeral deferred reply so subsequent interaction.reply() calls
+  // can safely edit the original deferred response.
+  if (shouldDefer) {
+    try {
+      await (interaction as AgentComponentMessageInteraction).defer({ ephemeral: true });
+      didDefer = true;
+    } catch (err) {
+      logError(`${label}: failed to defer interaction: ${String(err)}`);
+    }
+  }
+  const replyOpts = didDefer ? {} : { ephemeral: true };
+
+  const username = formatUsername(user);
+  const userId = user.id;
+
+  // P1 FIX: Use rawData.guild_id as source of truth - interaction.guild can be null
+  // when guild is not cached even though guild_id is present in rawData
+  const rawGuildId = interaction.rawData.guild_id;
+  const isDirectMessage = !rawGuildId;
+  const memberRoleIds = Array.isArray(interaction.rawData.member?.roles)
+    ? interaction.rawData.member.roles.map((roleId: string) => String(roleId))
+    : [];
+
+  return {
+    channelId,
+    user,
+    username,
+    userId,
+    replyOpts,
+    rawGuildId,
+    isDirectMessage,
+    memberRoleIds,
+  };
+}
+
+async function ensureGuildComponentMemberAllowed(params: {
+  interaction: AgentComponentInteraction;
+  guildInfo: ReturnType<typeof resolveDiscordGuildEntry>;
+  channelId: string;
+  rawGuildId: string | undefined;
+  channelCtx: DiscordChannelContext;
+  memberRoleIds: string[];
+  user: DiscordUser;
+  replyOpts: { ephemeral?: boolean };
+  componentLabel: string;
+  unauthorizedReply: string;
+  allowNameMatching: boolean;
+}): Promise<boolean> {
+  const {
+    interaction,
+    guildInfo,
+    channelId,
+    rawGuildId,
+    channelCtx,
+    memberRoleIds,
+    user,
+    replyOpts,
+    componentLabel,
+    unauthorizedReply,
+  } = params;
+
+  if (!rawGuildId) {
+    return true;
+  }
+
+  const channelConfig = resolveDiscordChannelConfigWithFallback({
+    guildInfo,
+    channelId,
+    channelName: channelCtx.channelName,
+    channelSlug: channelCtx.channelSlug,
+    parentId: channelCtx.parentId,
+    parentName: channelCtx.parentName,
+    parentSlug: channelCtx.parentSlug,
+    scope: channelCtx.isThread ? "thread" : "channel",
+  });
+
+  const { memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
+    memberRoleIds,
+    sender: {
+      id: user.id,
+      name: user.username,
+      tag: user.discriminator ? `${user.username}#${user.discriminator}` : undefined,
+    },
+    allowNameMatching: params.allowNameMatching,
+  });
+  if (memberAllowed) {
+    return true;
+  }
+
+  logVerbose(`agent ${componentLabel}: blocked user ${user.id} (not in users/roles allowlist)`);
+  try {
+    await interaction.reply({
+      content: unauthorizedReply,
+      ...replyOpts,
+    });
+  } catch {
+    // Interaction may have expired
+  }
+  return false;
+}
+
+async function ensureComponentUserAllowed(params: {
+  entry: DiscordComponentEntry;
+  interaction: AgentComponentInteraction;
+  user: DiscordUser;
+  replyOpts: { ephemeral?: boolean };
+  componentLabel: string;
+  unauthorizedReply: string;
+  allowNameMatching: boolean;
+}): Promise<boolean> {
+  const allowList = normalizeDiscordAllowList(params.entry.allowedUsers, [
+    "discord:",
+    "user:",
+    "pk:",
+  ]);
+  if (!allowList) {
+    return true;
+  }
+  const match = resolveDiscordAllowListMatch({
+    allowList,
+    candidate: {
+      id: params.user.id,
+      name: params.user.username,
+      tag: formatDiscordUserTag(params.user),
+    },
+    allowNameMatching: params.allowNameMatching,
+  });
+  if (match.allowed) {
+    return true;
+  }
+
+  logVerbose(
+    `discord component ${params.componentLabel}: blocked user ${params.user.id} (not in allowedUsers)`,
+  );
+  try {
+    await params.interaction.reply({
+      content: params.unauthorizedReply,
+      ...params.replyOpts,
+    });
+  } catch {
+    // Interaction may have expired
+  }
+  return false;
+}
+
+async function ensureAgentComponentInteractionAllowed(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  channelId: string;
+  rawGuildId: string | undefined;
+  memberRoleIds: string[];
+  user: DiscordUser;
+  replyOpts: { ephemeral?: boolean };
+  componentLabel: string;
+  unauthorizedReply: string;
+}): Promise<{ parentId: string | undefined } | null> {
+  const guildInfo = resolveDiscordGuildEntry({
+    guild: params.interaction.guild ?? undefined,
+    guildId: params.rawGuildId,
+    guildEntries: params.ctx.guildEntries,
+  });
+  const channelCtx = resolveDiscordChannelContext(params.interaction);
+  const memberAllowed = await ensureGuildComponentMemberAllowed({
+    interaction: params.interaction,
+    guildInfo,
+    channelId: params.channelId,
+    rawGuildId: params.rawGuildId,
+    channelCtx,
+    memberRoleIds: params.memberRoleIds,
+    user: params.user,
+    replyOpts: params.replyOpts,
+    componentLabel: params.componentLabel,
+    unauthorizedReply: params.unauthorizedReply,
+    allowNameMatching: isDangerousNameMatchingEnabled(params.ctx.discordConfig),
+  });
+  if (!memberAllowed) {
+    return null;
+  }
+  return { parentId: channelCtx.parentId };
+}
+
+export type AgentComponentContext = {
+  cfg: OpenClawConfig;
+  accountId: string;
+  discordConfig?: DiscordAccountConfig;
+  runtime?: RuntimeEnv;
+  token?: string;
+  guildEntries?: Record<string, DiscordGuildEntryResolved>;
+  /** DM allowlist (from allowFrom config; legacy: dm.allowFrom) */
+  allowFrom?: string[];
+  /** DM policy (default: "pairing") */
+  dmPolicy?: "open" | "pairing" | "allowlist" | "disabled";
+};
+
+/**
+ * Build agent button custom ID: agent:componentId=<id>
+ * The channelId is NOT embedded in customId - we use interaction.rawData.channel_id instead
+ * to prevent channel spoofing attacks.
+ *
+ * Carbon's customIdParser parses "key:arg1=value1;arg2=value2" into { arg1: value1, arg2: value2 }
+ */
+export function buildAgentButtonCustomId(componentId: string): string {
+  return `${AGENT_BUTTON_KEY}:componentId=${encodeURIComponent(componentId)}`;
+}
+
+/**
+ * Build agent select menu custom ID: agentsel:componentId=<id>
+ */
+export function buildAgentSelectCustomId(componentId: string): string {
+  return `${AGENT_SELECT_KEY}:componentId=${encodeURIComponent(componentId)}`;
+}
+
+/**
+ * Parse agent component data from Carbon's parsed ComponentData
+ * Supports both legacy { componentId } and Components v2 { cid } payloads.
+ */
+function readParsedComponentId(data: ComponentData): unknown {
+  if (!data || typeof data !== "object") {
+    return undefined;
+  }
+  return "cid" in data
+    ? (data as Record<string, unknown>).cid
+    : (data as Record<string, unknown>).componentId;
+}
+
+function parseAgentComponentData(data: ComponentData): {
+  componentId: string;
+} | null {
+  const raw = readParsedComponentId(data);
+
+  const decodeSafe = (value: string): string => {
+    // `cid` values may be raw (not URI-encoded). Guard against malformed % sequences.
+    // Only attempt decoding when it looks like it contains percent-encoding.
+    if (!value.includes("%")) {
+      return value;
+    }
+    // If it has a % but not a valid %XX sequence, skip decode.
+    if (!/%[0-9A-Fa-f]{2}/.test(value)) {
+      return value;
+    }
+    try {
+      return decodeURIComponent(value);
+    } catch {
+      return value;
+    }
+  };
+
+  const componentId =
+    typeof raw === "string" ? decodeSafe(raw) : typeof raw === "number" ? String(raw) : null;
+
+  if (!componentId) {
+    return null;
+  }
+  return { componentId };
+}
+
+function formatUsername(user: { username: string; discriminator?: string | null }): string {
+  if (user.discriminator && user.discriminator !== "0") {
+    return `${user.username}#${user.discriminator}`;
+  }
+  return user.username;
+}
+
+/**
+ * Check if a channel type is a thread type
+ */
+function isThreadChannelType(channelType: number | undefined): boolean {
+  return (
+    channelType === ChannelType.PublicThread ||
+    channelType === ChannelType.PrivateThread ||
+    channelType === ChannelType.AnnouncementThread
+  );
+}
+
+async function ensureDmComponentAuthorized(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  user: DiscordUser;
+  componentLabel: string;
+  replyOpts: { ephemeral?: boolean };
+}): Promise<boolean> {
+  const { ctx, interaction, user, componentLabel, replyOpts } = params;
+  const dmPolicy = ctx.dmPolicy ?? "pairing";
+  if (dmPolicy === "disabled") {
+    logVerbose(`agent ${componentLabel}: blocked (DM policy disabled)`);
+    try {
+      await interaction.reply({
+        content: "DM interactions are disabled.",
+        ...replyOpts,
+      });
+    } catch {
+      // Interaction may have expired
+    }
+    return false;
+  }
+  if (dmPolicy === "open") {
+    return true;
+  }
+
+  const storeAllowFrom = await readStoreAllowFromForDmPolicy({
+    provider: "discord",
+    accountId: ctx.accountId,
+    dmPolicy,
+  });
+  const effectiveAllowFrom = [...(ctx.allowFrom ?? []), ...storeAllowFrom];
+  const allowList = normalizeDiscordAllowList(effectiveAllowFrom, ["discord:", "user:", "pk:"]);
+  const allowMatch = allowList
+    ? resolveDiscordAllowListMatch({
+        allowList,
+        candidate: {
+          id: user.id,
+          name: user.username,
+          tag: formatDiscordUserTag(user),
+        },
+        allowNameMatching: isDangerousNameMatchingEnabled(ctx.discordConfig),
+      })
+    : { allowed: false };
+  if (allowMatch.allowed) {
+    return true;
+  }
+
+  if (dmPolicy === "pairing") {
+    const pairingResult = await issuePairingChallenge({
+      channel: "discord",
+      senderId: user.id,
+      senderIdLine: `Your Discord user id: ${user.id}`,
+      meta: {
+        tag: formatDiscordUserTag(user),
+        name: user.username,
+      },
+      upsertPairingRequest: async ({ id, meta }) =>
+        await upsertChannelPairingRequest({
+          channel: "discord",
+          id,
+          accountId: ctx.accountId,
+          meta,
+        }),
+      sendPairingReply: async (text) => {
+        await interaction.reply({
+          content: text,
+          ...replyOpts,
+        });
+      },
+    });
+    if (!pairingResult.created) {
+      try {
+        await interaction.reply({
+          content: "Pairing already requested. Ask the bot owner to approve your code.",
+          ...replyOpts,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+    }
+    return false;
+  }
+
+  logVerbose(`agent ${componentLabel}: blocked DM user ${user.id} (not in allowFrom)`);
+  try {
+    await interaction.reply({
+      content: `You are not authorized to use this ${componentLabel}.`,
+      ...replyOpts,
+    });
+  } catch {
+    // Interaction may have expired
+  }
+  return false;
+}
+
+async function resolveInteractionContextWithDmAuth(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  label: string;
+  componentLabel: string;
+  defer?: boolean;
+}): Promise<ComponentInteractionContext | null> {
+  const interactionCtx = await resolveComponentInteractionContext({
+    interaction: params.interaction,
+    label: params.label,
+    defer: params.defer,
+  });
+  if (!interactionCtx) {
+    return null;
+  }
+  if (interactionCtx.isDirectMessage) {
+    const authorized = await ensureDmComponentAuthorized({
+      ctx: params.ctx,
+      interaction: params.interaction,
+      user: interactionCtx.user,
+      componentLabel: params.componentLabel,
+      replyOpts: interactionCtx.replyOpts,
+    });
+    if (!authorized) {
+      return null;
+    }
+  }
+  return interactionCtx;
+}
+
+function normalizeComponentId(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return undefined;
+}
+
+function parseDiscordComponentData(
+  data: ComponentData,
+  customId?: string,
+): { componentId: string; modalId?: string } | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const rawComponentId = readParsedComponentId(data);
+  const rawModalId =
+    "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
+  let componentId = normalizeComponentId(rawComponentId);
+  let modalId = normalizeComponentId(rawModalId);
+  if (!componentId && customId) {
+    const parsed = parseDiscordComponentCustomId(customId);
+    if (parsed) {
+      componentId = parsed.componentId;
+      modalId = parsed.modalId;
+    }
+  }
+  if (!componentId) {
+    return null;
+  }
+  return { componentId, modalId };
+}
+
+function parseDiscordModalId(data: ComponentData, customId?: string): string | null {
+  if (data && typeof data === "object") {
+    const rawModalId =
+      "mid" in data ? (data as { mid?: unknown }).mid : (data as { modalId?: unknown }).modalId;
+    const modalId = normalizeComponentId(rawModalId);
+    if (modalId) {
+      return modalId;
+    }
+  }
+  if (customId) {
+    return parseDiscordModalCustomId(customId);
+  }
+  return null;
+}
+
+function resolveInteractionCustomId(interaction: AgentComponentInteraction): string | undefined {
+  if (!interaction?.rawData || typeof interaction.rawData !== "object") {
+    return undefined;
+  }
+  if (!("data" in interaction.rawData)) {
+    return undefined;
+  }
+  const data = (interaction.rawData as { data?: { custom_id?: unknown } }).data;
+  const customId = data?.custom_id;
+  if (typeof customId !== "string") {
+    return undefined;
+  }
+  const trimmed = customId.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function mapOptionLabels(
+  options: Array<{ value: string; label: string }> | undefined,
+  values: string[],
+) {
+  if (!options || options.length === 0) {
+    return values;
+  }
+  const map = new Map(options.map((option) => [option.value, option.label]));
+  return values.map((value) => map.get(value) ?? value);
+}
+
+function mapSelectValues(entry: DiscordComponentEntry, values: string[]): string[] {
+  if (entry.selectType === "string") {
+    return mapOptionLabels(entry.options, values);
+  }
+  if (entry.selectType === "user") {
+    return values.map((value) => `user:${value}`);
+  }
+  if (entry.selectType === "role") {
+    return values.map((value) => `role:${value}`);
+  }
+  if (entry.selectType === "mentionable") {
+    return values.map((value) => `mentionable:${value}`);
+  }
+  if (entry.selectType === "channel") {
+    return values.map((value) => `channel:${value}`);
+  }
+  return values;
+}
+
+function resolveModalFieldValues(
+  field: DiscordModalEntry["fields"][number],
+  interaction: ModalInteraction,
+): string[] {
+  const fields = interaction.fields;
+  const optionLabels = field.options?.map((option) => ({
+    value: option.value,
+    label: option.label,
+  }));
+  const required = field.required === true;
+  try {
+    switch (field.type) {
+      case "text": {
+        const value = required ? fields.getText(field.id, true) : fields.getText(field.id);
+        return value ? [value] : [];
+      }
+      case "select":
+      case "checkbox":
+      case "radio": {
+        const values = required
+          ? fields.getStringSelect(field.id, true)
+          : (fields.getStringSelect(field.id) ?? []);
+        return mapOptionLabels(optionLabels, values);
+      }
+      case "role-select": {
+        try {
+          const roles = required
+            ? fields.getRoleSelect(field.id, true)
+            : (fields.getRoleSelect(field.id) ?? []);
+          return roles.map((role) => role.name ?? role.id);
+        } catch {
+          const values = required
+            ? fields.getStringSelect(field.id, true)
+            : (fields.getStringSelect(field.id) ?? []);
+          return values;
+        }
+      }
+      case "user-select": {
+        const users = required
+          ? fields.getUserSelect(field.id, true)
+          : (fields.getUserSelect(field.id) ?? []);
+        return users.map((user) => formatDiscordUserTag(user));
+      }
+      default:
+        return [];
+    }
+  } catch (err) {
+    logError(`agent modal: failed to read field ${field.id}: ${String(err)}`);
+    return [];
+  }
+}
+
+function formatModalSubmissionText(
+  entry: DiscordModalEntry,
+  interaction: ModalInteraction,
+): string {
+  const lines: string[] = [`Form "${entry.title}" submitted.`];
+  for (const field of entry.fields) {
+    const values = resolveModalFieldValues(field, interaction);
+    if (values.length === 0) {
+      continue;
+    }
+    lines.push(`- ${field.label}: ${values.join(", ")}`);
+  }
+  if (lines.length === 1) {
+    lines.push("- (no values)");
+  }
+  return lines.join("\n");
+}
+
+function resolveDiscordInteractionId(interaction: AgentComponentInteraction): string {
+  const rawId =
+    interaction.rawData && typeof interaction.rawData === "object" && "id" in interaction.rawData
+      ? (interaction.rawData as { id?: unknown }).id
+      : undefined;
+  if (typeof rawId === "string" && rawId.trim()) {
+    return rawId.trim();
+  }
+  if (typeof rawId === "number" && Number.isFinite(rawId)) {
+    return String(rawId);
+  }
+  return `discord-interaction:${Date.now()}`;
+}
+
 async function dispatchPluginDiscordInteractiveEvent(params: {
   ctx: AgentComponentContext;
   interaction: AgentComponentInteraction;
@@ -239,6 +931,54 @@ async function dispatchPluginDiscordInteractiveEvent(params: {
   return "unmatched";
 }
 
+function resolveComponentCommandAuthorized(params: {
+  ctx: AgentComponentContext;
+  interactionCtx: ComponentInteractionContext;
+  channelConfig: ReturnType<typeof resolveDiscordChannelConfigWithFallback>;
+  guildInfo: ReturnType<typeof resolveDiscordGuildEntry>;
+  allowNameMatching: boolean;
+}): boolean {
+  const { ctx, interactionCtx, channelConfig, guildInfo } = params;
+  if (interactionCtx.isDirectMessage) {
+    return true;
+  }
+
+  const { ownerAllowList, ownerAllowed: ownerOk } = resolveDiscordOwnerAccess({
+    allowFrom: ctx.allowFrom,
+    sender: {
+      id: interactionCtx.user.id,
+      name: interactionCtx.user.username,
+      tag: formatDiscordUserTag(interactionCtx.user),
+    },
+    allowNameMatching: params.allowNameMatching,
+  });
+
+  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
+    memberRoleIds: interactionCtx.memberRoleIds,
+    sender: {
+      id: interactionCtx.user.id,
+      name: interactionCtx.user.username,
+      tag: formatDiscordUserTag(interactionCtx.user),
+    },
+    allowNameMatching: params.allowNameMatching,
+  });
+  const useAccessGroups = ctx.cfg.commands?.useAccessGroups !== false;
+  const authorizers = useAccessGroups
+    ? [
+        { configured: ownerAllowList != null, allowed: ownerOk },
+        { configured: hasAccessRestrictions, allowed: memberAllowed },
+      ]
+    : [{ configured: hasAccessRestrictions, allowed: memberAllowed }];
+
+  return resolveCommandAuthorizedFromAuthorizers({
+    useAccessGroups,
+    authorizers,
+    modeWhenAccessGroupsOff: "configured",
+  });
+}
+
 async function dispatchDiscordComponentEvent(params: {
   ctx: AgentComponentContext;
   interaction: AgentComponentInteraction;
@@ -305,7 +1045,7 @@ async function dispatchDiscordComponentEvent(params: {
     ? resolvePinnedMainDmOwnerFromAllowlist({
         dmScope: ctx.cfg.session?.dmScope,
         allowFrom: channelConfig?.users ?? guildInfo?.users,
-        normalizeEntry: (entry: string) => {
+        normalizeEntry: (entry) => {
           const normalized = normalizeDiscordAllowList([entry], ["discord:", "user:", "pk:"]);
           const candidate = normalized?.ids.values().next().value;
           return typeof candidate === "string" && /^\d+$/.test(candidate) ? candidate : undefined;

extensions/discord/src/monitor/monitor.test.ts

@@ -7,11 +7,11 @@ import type {
 import type { Client } from "@buape/carbon";
 import { ChannelType } from "discord-api-types/v10";
 import type { GatewayPresenceUpdate } from "discord-api-types/v10";
-import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
-import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-runtime";
-import { buildPluginBindingApprovalCustomId } from "openclaw/plugin-sdk/conversation-runtime";
-import { buildAgentSessionKey } from "openclaw/plugin-sdk/routing";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../../../src/config/config.js";
+import type { DiscordAccountConfig } from "../../../../src/config/types.discord.js";
+import { buildPluginBindingApprovalCustomId } from "../../../../src/plugins/conversation-binding.js";
+import { buildAgentSessionKey } from "../../../../src/routing/resolve-route.js";
 import {
   clearDiscordComponentEntries,
   registerDiscordComponentEntries,
@@ -50,6 +50,7 @@ const readAllowFromStoreMock = vi.hoisted(() => vi.fn());
 const upsertPairingRequestMock = vi.hoisted(() => vi.fn());
 const enqueueSystemEventMock = vi.hoisted(() => vi.fn());
 const dispatchReplyMock = vi.hoisted(() => vi.fn());
+const deliverDiscordReplyMock = vi.hoisted(() => vi.fn());
 const recordInboundSessionMock = vi.hoisted(() => vi.fn());
 const readSessionUpdatedAtMock = vi.hoisted(() => vi.fn());
 const resolveStorePathMock = vi.hoisted(() => vi.fn());
@@ -58,20 +59,37 @@ const resolvePluginConversationBindingApprovalMock = vi.hoisted(() => vi.fn());
 const buildPluginBindingResolvedTextMock = vi.hoisted(() => vi.fn());
 let lastDispatchCtx: Record<string, unknown> | undefined;
 
-vi.mock("../../../../src/security/dm-policy-shared.js", async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import("../../../../src/security/dm-policy-shared.js")>();
+vi.mock("../../../../src/pairing/pairing-store.js", () => ({
+  readChannelAllowFromStore: (...args: unknown[]) => readAllowFromStoreMock(...args),
+  upsertChannelPairingRequest: (...args: unknown[]) => upsertPairingRequestMock(...args),
+}));
+
+vi.mock("../../../../src/infra/system-events.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../../src/infra/system-events.js")>();
   return {
     ...actual,
-    readStoreAllowFromForDmPolicy: (...args: unknown[]) => readAllowFromStoreMock(...args),
+    enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
   };
 });
 
-vi.mock("../../../../src/pairing/pairing-store.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../../../src/pairing/pairing-store.js")>();
+vi.mock("../../../../src/auto-reply/reply/provider-dispatcher.js", () => ({
+  dispatchReplyWithBufferedBlockDispatcher: (...args: unknown[]) => dispatchReplyMock(...args),
+}));
+
+vi.mock("./reply-delivery.js", () => ({
+  deliverDiscordReply: (...args: unknown[]) => deliverDiscordReplyMock(...args),
+}));
+
+vi.mock("../../../../src/channels/session.js", () => ({
+  recordInboundSession: (...args: unknown[]) => recordInboundSessionMock(...args),
+}));
+
+vi.mock("../../../../src/config/sessions.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../../../src/config/sessions.js")>();
   return {
     ...actual,
-    upsertChannelPairingRequest: (...args: unknown[]) => upsertPairingRequestMock(...args),
+    readSessionUpdatedAt: (...args: unknown[]) => readSessionUpdatedAtMock(...args),
+    resolveStorePath: (...args: unknown[]) => resolveStorePathMock(...args),
   };
 });
 
@@ -87,42 +105,6 @@ vi.mock("../../../../src/plugins/conversation-binding.js", async (importOriginal
   };
 });
 
-vi.mock("../../../../src/infra/system-events.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../../../src/infra/system-events.js")>();
-  return {
-    ...actual,
-    enqueueSystemEvent: (...args: unknown[]) => enqueueSystemEventMock(...args),
-  };
-});
-
-vi.mock("../../../../src/auto-reply/reply/provider-dispatcher.js", async (importOriginal) => {
-  const actual =
-    await importOriginal<
-      typeof import("../../../../src/auto-reply/reply/provider-dispatcher.js")
-    >();
-  return {
-    ...actual,
-    dispatchReplyWithBufferedBlockDispatcher: (...args: unknown[]) => dispatchReplyMock(...args),
-  };
-});
-
-vi.mock("../../../../src/channels/session.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../../../src/channels/session.js")>();
-  return {
-    ...actual,
-    recordInboundSession: (...args: unknown[]) => recordInboundSessionMock(...args),
-  };
-});
-
-vi.mock("../../../../src/config/sessions.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../../../../src/config/sessions.js")>();
-  return {
-    ...actual,
-    readSessionUpdatedAt: (...args: unknown[]) => readSessionUpdatedAtMock(...args),
-    resolveStorePath: (...args: unknown[]) => resolveStorePathMock(...args),
-  };
-});
-
 vi.mock("../../../../src/plugins/interactive.js", async (importOriginal) => {
   const actual = await importOriginal<typeof import("../../../../src/plugins/interactive.js")>();
   return {
@@ -305,18 +287,12 @@ describe("discord component interactions", () => {
   const createComponentButtonInteraction = (overrides: Partial<ButtonInteraction> = {}) => {
     const reply = vi.fn().mockResolvedValue(undefined);
     const defer = vi.fn().mockResolvedValue(undefined);
-    const rest = {
-      get: vi.fn().mockResolvedValue({ type: ChannelType.DM }),
-      post: vi.fn().mockResolvedValue({}),
-      patch: vi.fn().mockResolvedValue({}),
-      delete: vi.fn().mockResolvedValue(undefined),
-    };
     const interaction = {
       rawData: { channel_id: "dm-channel", id: "interaction-1" },
       user: { id: "123456789", username: "AgentUser", discriminator: "0001" },
       customId: "occomp:cid=btn_1",
       message: { id: "msg-1" },
-      client: { rest },
+      client: { rest: {} },
       defer,
       reply,
       ...overrides,
@@ -327,12 +303,6 @@ describe("discord component interactions", () => {
   const createModalInteraction = (overrides: Partial<ModalInteraction> = {}) => {
     const reply = vi.fn().mockResolvedValue(undefined);
     const acknowledge = vi.fn().mockResolvedValue(undefined);
-    const rest = {
-      get: vi.fn().mockResolvedValue({ type: ChannelType.DM }),
-      post: vi.fn().mockResolvedValue({}),
-      patch: vi.fn().mockResolvedValue({}),
-      delete: vi.fn().mockResolvedValue(undefined),
-    };
     const fields = {
       getText: (key: string) => (key === "fld_1" ? "Casey" : undefined),
       getStringSelect: (_key: string) => undefined,
@@ -346,7 +316,7 @@ describe("discord component interactions", () => {
       fields,
       acknowledge,
       reply,
-      client: { rest },
+      client: { rest: {} },
       ...overrides,
     } as unknown as ModalInteraction;
     return { interaction, acknowledge, reply };
@@ -393,6 +363,7 @@ describe("discord component interactions", () => {
       lastDispatchCtx = params.ctx;
       await params.dispatcherOptions.deliver({ text: "ok" });
     });
+    deliverDiscordReplyMock.mockClear();
     recordInboundSessionMock.mockClear().mockResolvedValue(undefined);
     readSessionUpdatedAtMock.mockClear().mockReturnValue(undefined);
     resolveStorePathMock.mockClear().mockReturnValue("/tmp/openclaw-sessions-test.json");
@@ -444,6 +415,8 @@ describe("discord component interactions", () => {
     expect(reply).toHaveBeenCalledWith({ content: "✓" });
     expect(lastDispatchCtx?.BodyForAgent).toBe('Clicked "Approve".');
     expect(dispatchReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock.mock.calls[0]?.[0]?.replyToId).toBe("msg-1");
     expect(resolveDiscordComponentEntry({ id: "btn_1" })).toBeNull();
   });
 
@@ -509,6 +482,8 @@ describe("discord component interactions", () => {
     expect(lastDispatchCtx?.BodyForAgent).toContain('Form "Details" submitted.');
     expect(lastDispatchCtx?.BodyForAgent).toContain("- Name: Casey");
     expect(dispatchReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock).toHaveBeenCalledTimes(1);
+    expect(deliverDiscordReplyMock.mock.calls[0]?.[0]?.replyToId).toBe("msg-2");
     expect(resolveDiscordModalEntry({ id: "mdl_1" })).toBeNull();
   });
 

extensions/discord/src/monitor/native-command.plugin-dispatch.test.ts

@@ -2,7 +2,7 @@ import { ChannelType } from "discord-api-types/v10";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { NativeCommandSpec } from "../../../../src/auto-reply/commands-registry.js";
 import * as dispatcherModule from "../../../../src/auto-reply/reply/provider-dispatcher.js";
-import { setDefaultChannelPluginRegistryForTests } from "../../../../src/commands/channel-test-helpers.js";
+import type { ChatType } from "../../../../src/channels/chat-type.js";
 import type { OpenClawConfig } from "../../../../src/config/config.js";
 import * as pluginCommandsModule from "../../../../src/plugins/commands.js";
 import { clearPluginCommands, registerPluginCommand } from "../../../../src/plugins/commands.js";
@@ -12,26 +12,32 @@ import {
 } from "./native-command.test-helpers.js";
 import { createNoopThreadBindingManager } from "./thread-bindings.js";
 
+type ResolveConfiguredBindingRouteFn =
+  typeof import("openclaw/plugin-sdk/conversation-runtime").resolveConfiguredBindingRoute;
 type EnsureConfiguredBindingRouteReadyFn =
   typeof import("openclaw/plugin-sdk/conversation-runtime").ensureConfiguredBindingRouteReady;
 
-const ensureConfiguredBindingRouteReadyMock = vi.hoisted(() =>
-  vi.fn<EnsureConfiguredBindingRouteReadyFn>(async () => ({
+const persistentBindingMocks = vi.hoisted(() => ({
+  resolveConfiguredAcpBindingRecord: vi.fn<ResolveConfiguredBindingRouteFn>((params) => ({
+    bindingResolution: null,
+    route: params.route,
+  })),
+  ensureConfiguredAcpBindingSession: vi.fn<EnsureConfiguredBindingRouteReadyFn>(async () => ({
     ok: true,
   })),
-);
+}));
 
 vi.mock("openclaw/plugin-sdk/conversation-runtime", async (importOriginal) => {
   const actual = await importOriginal<typeof import("openclaw/plugin-sdk/conversation-runtime")>();
   return {
     ...actual,
-    ensureConfiguredBindingRouteReady: (...args: unknown[]) =>
-      ensureConfiguredBindingRouteReadyMock(
-        ...(args as Parameters<EnsureConfiguredBindingRouteReadyFn>),
-      ),
+    resolveConfiguredBindingRoute: persistentBindingMocks.resolveConfiguredAcpBindingRecord,
+    ensureConfiguredBindingRouteReady: persistentBindingMocks.ensureConfiguredAcpBindingSession,
   };
 });
 
+import { createDiscordNativeCommand } from "./native-command.js";
+
 function createInteraction(params?: {
   channelType?: ChannelType;
   channelId?: string;
@@ -60,12 +66,7 @@ function createConfig(): OpenClawConfig {
   } as OpenClawConfig;
 }
 
-async function loadCreateDiscordNativeCommand() {
-  return (await import("./native-command.js")).createDiscordNativeCommand;
-}
-
-async function createNativeCommand(cfg: OpenClawConfig, commandSpec: NativeCommandSpec) {
-  const createDiscordNativeCommand = await loadCreateDiscordNativeCommand();
+function createNativeCommand(cfg: OpenClawConfig, commandSpec: NativeCommandSpec) {
   return createDiscordNativeCommand({
     command: commandSpec,
     cfg,
@@ -77,8 +78,7 @@ async function createNativeCommand(cfg: OpenClawConfig, commandSpec: NativeComma
   });
 }
 
-async function createPluginCommand(params: { cfg: OpenClawConfig; name: string }) {
-  const createDiscordNativeCommand = await loadCreateDiscordNativeCommand();
+function createPluginCommand(params: { cfg: OpenClawConfig; name: string }) {
   return createDiscordNativeCommand({
     command: {
       name: params.name,
@@ -119,7 +119,7 @@ async function expectPairCommandReply(params: {
   commandName: string;
   interaction: MockCommandInteraction;
 }) {
-  const command = await createPluginCommand({
+  const command = createPluginCommand({
     cfg: params.cfg,
     name: params.commandName,
   });
@@ -143,14 +143,150 @@ async function expectPairCommandReply(params: {
   );
 }
 
-async function createStatusCommand(cfg: OpenClawConfig) {
-  return await createNativeCommand(cfg, {
+function createStatusCommand(cfg: OpenClawConfig) {
+  return createNativeCommand(cfg, {
     name: "status",
     description: "Status",
     acceptsArgs: false,
   });
 }
 
+function resolveConversationFromParams(params: Parameters<ResolveConfiguredBindingRouteFn>[0]) {
+  if ("conversation" in params) {
+    return params.conversation;
+  }
+  return {
+    channel: params.channel,
+    accountId: params.accountId,
+    conversationId: params.conversationId,
+    ...(params.parentConversationId ? { parentConversationId: params.parentConversationId } : {}),
+  };
+}
+
+function createConfiguredBindingResolution(params: {
+  conversation: ReturnType<typeof resolveConversationFromParams>;
+  boundSessionKey: string;
+}) {
+  const peerKind: ChatType = params.conversation.conversationId.startsWith("dm-")
+    ? "direct"
+    : "channel";
+  const configuredBinding = {
+    spec: {
+      channel: "discord" as const,
+      accountId: params.conversation.accountId,
+      conversationId: params.conversation.conversationId,
+      ...(params.conversation.parentConversationId
+        ? { parentConversationId: params.conversation.parentConversationId }
+        : {}),
+      agentId: "codex",
+      mode: "persistent" as const,
+    },
+    record: {
+      bindingId: `config:acp:discord:${params.conversation.accountId}:${params.conversation.conversationId}`,
+      targetSessionKey: params.boundSessionKey,
+      targetKind: "session" as const,
+      conversation: params.conversation,
+      status: "active" as const,
+      boundAt: 0,
+    },
+  };
+  return {
+    conversation: params.conversation,
+    compiledBinding: {
+      channel: "discord" as const,
+      binding: {
+        type: "acp" as const,
+        agentId: "codex",
+        match: {
+          channel: "discord",
+          accountId: params.conversation.accountId,
+          peer: {
+            kind: peerKind,
+            id: params.conversation.conversationId,
+          },
+        },
+        acp: {
+          mode: "persistent" as const,
+        },
+      },
+      bindingConversationId: params.conversation.conversationId,
+      target: {
+        conversationId: params.conversation.conversationId,
+        ...(params.conversation.parentConversationId
+          ? { parentConversationId: params.conversation.parentConversationId }
+          : {}),
+      },
+      agentId: "codex",
+      provider: {
+        compileConfiguredBinding: () => ({
+          conversationId: params.conversation.conversationId,
+          ...(params.conversation.parentConversationId
+            ? { parentConversationId: params.conversation.parentConversationId }
+            : {}),
+        }),
+        matchInboundConversation: () => ({
+          conversationId: params.conversation.conversationId,
+          ...(params.conversation.parentConversationId
+            ? { parentConversationId: params.conversation.parentConversationId }
+            : {}),
+        }),
+      },
+      targetFactory: {
+        driverId: "acp" as const,
+        materialize: () => ({
+          record: configuredBinding.record,
+          statefulTarget: {
+            kind: "stateful" as const,
+            driverId: "acp",
+            sessionKey: params.boundSessionKey,
+            agentId: "codex",
+          },
+        }),
+      },
+    },
+    match: {
+      conversationId: params.conversation.conversationId,
+      ...(params.conversation.parentConversationId
+        ? { parentConversationId: params.conversation.parentConversationId }
+        : {}),
+    },
+    record: configuredBinding.record,
+    statefulTarget: {
+      kind: "stateful" as const,
+      driverId: "acp",
+      sessionKey: params.boundSessionKey,
+      agentId: "codex",
+    },
+  };
+}
+
+function setConfiguredBinding(channelId: string, boundSessionKey: string) {
+  persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockImplementation((params) => {
+    const conversation = resolveConversationFromParams(params);
+    const bindingResolution = createConfiguredBindingResolution({
+      conversation: {
+        ...conversation,
+        conversationId: channelId,
+      },
+      boundSessionKey,
+    });
+    return {
+      bindingResolution,
+      boundSessionKey,
+      boundAgentId: "codex",
+      route: {
+        ...params.route,
+        agentId: "codex",
+        sessionKey: boundSessionKey,
+        matchedBy: "binding.channel",
+      },
+    };
+  });
+  persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
+    ok: true,
+  });
+}
+
 function createDispatchSpy() {
   return vi.spyOn(dispatcherModule, "dispatchReplyWithDispatcher").mockResolvedValue({
     counts: {
@@ -163,23 +299,26 @@ function createDispatchSpy() {
 
 function expectBoundSessionDispatch(
   dispatchSpy: ReturnType<typeof createDispatchSpy>,
-  expectedPattern: RegExp,
+  boundSessionKey: string,
 ) {
   expect(dispatchSpy).toHaveBeenCalledTimes(1);
   const dispatchCall = dispatchSpy.mock.calls[0]?.[0] as {
     ctx?: { SessionKey?: string; CommandTargetSessionKey?: string };
   };
-  expect(dispatchCall.ctx?.SessionKey).toMatch(expectedPattern);
-  expect(dispatchCall.ctx?.CommandTargetSessionKey).toMatch(expectedPattern);
-  expect(ensureConfiguredBindingRouteReadyMock).toHaveBeenCalledTimes(1);
+  expect(dispatchCall.ctx?.SessionKey).toBe(boundSessionKey);
+  expect(dispatchCall.ctx?.CommandTargetSessionKey).toBe(boundSessionKey);
+  expect(persistentBindingMocks.resolveConfiguredAcpBindingRecord).toHaveBeenCalledTimes(1);
+  expect(persistentBindingMocks.ensureConfiguredAcpBindingSession).toHaveBeenCalledTimes(1);
 }
 
 async function expectBoundStatusCommandDispatch(params: {
   cfg: OpenClawConfig;
   interaction: MockCommandInteraction;
-  expectedPattern: RegExp;
+  channelId: string;
+  boundSessionKey: string;
 }) {
-  const command = await createStatusCommand(params.cfg);
+  const command = createStatusCommand(params.cfg);
+  setConfiguredBinding(params.channelId, params.boundSessionKey);
 
   vi.spyOn(pluginCommandsModule, "matchPluginCommand").mockReturnValue(null);
   const dispatchSpy = createDispatchSpy();
@@ -188,16 +327,20 @@ async function expectBoundStatusCommandDispatch(params: {
     params.interaction as unknown,
   );
 
-  expectBoundSessionDispatch(dispatchSpy, params.expectedPattern);
+  expectBoundSessionDispatch(dispatchSpy, params.boundSessionKey);
 }
 
 describe("Discord native plugin command dispatch", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
+    vi.restoreAllMocks();
     clearPluginCommands();
-    setDefaultChannelPluginRegistryForTests();
-    ensureConfiguredBindingRouteReadyMock.mockReset();
-    ensureConfiguredBindingRouteReadyMock.mockResolvedValue({
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReset();
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockImplementation((params) => ({
+      bindingResolution: null,
+      route: params.route,
+    }));
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockReset();
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
       ok: true,
     });
   });
@@ -254,7 +397,15 @@ describe("Discord native plugin command dispatch", () => {
       description: "Pair",
       acceptsArgs: true,
     };
-    const command = await createNativeCommand(cfg, commandSpec);
+    const command = createDiscordNativeCommand({
+      command: commandSpec,
+      cfg,
+      discordConfig: cfg.channels?.discord ?? {},
+      accountId: "default",
+      sessionPrefix: "discord:slash",
+      ephemeralDefault: true,
+      threadBindings: createNoopThreadBindingManager("default"),
+    });
     const interaction = createInteraction({
       channelType: ChannelType.GuildText,
       channelId: "234567890123456789",
@@ -298,7 +449,15 @@ describe("Discord native plugin command dispatch", () => {
       description: "List cron jobs",
       acceptsArgs: false,
     };
-    const command = await createNativeCommand(cfg, commandSpec);
+    const command = createDiscordNativeCommand({
+      command: commandSpec,
+      cfg,
+      discordConfig: cfg.channels?.discord ?? {},
+      accountId: "default",
+      sessionPrefix: "discord:slash",
+      ephemeralDefault: true,
+      threadBindings: createNoopThreadBindingManager("default"),
+    });
     const interaction = createInteraction();
     const pluginMatch = {
       command: {
@@ -333,21 +492,11 @@ describe("Discord native plugin command dispatch", () => {
   it("routes native slash commands through configured ACP Discord channel bindings", async () => {
     const guildId = "1459246755253325866";
     const channelId = "1478836151241412759";
+    const boundSessionKey = "agent:codex:acp:binding:discord:default:feedface";
     const cfg = {
       commands: {
         useAccessGroups: false,
       },
-      channels: {
-        discord: {
-          guilds: {
-            [guildId]: {
-              channels: {
-                [channelId]: { allow: true, requireMention: false },
-              },
-            },
-          },
-        },
-      },
       bindings: [
         {
           type: "acp",
@@ -373,7 +522,8 @@ describe("Discord native plugin command dispatch", () => {
     await expectBoundStatusCommandDispatch({
       cfg,
       interaction,
-      expectedPattern: /^agent:codex:acp:binding:discord:default:/,
+      channelId,
+      boundSessionKey,
     });
   });
 
@@ -407,7 +557,7 @@ describe("Discord native plugin command dispatch", () => {
         },
       },
     } as OpenClawConfig;
-    const command = await createStatusCommand(cfg);
+    const command = createStatusCommand(cfg);
     const interaction = createInteraction({
       channelType: ChannelType.GuildText,
       channelId,
@@ -428,11 +578,13 @@ describe("Discord native plugin command dispatch", () => {
     expect(dispatchCall.ctx?.CommandTargetSessionKey).toBe(
       "agent:qwen:discord:channel:1478836151241412759",
     );
-    expect(ensureConfiguredBindingRouteReadyMock).not.toHaveBeenCalled();
+    expect(persistentBindingMocks.resolveConfiguredAcpBindingRecord).toHaveBeenCalledTimes(1);
+    expect(persistentBindingMocks.ensureConfiguredAcpBindingSession).not.toHaveBeenCalled();
   });
 
   it("routes Discord DM native slash commands through configured ACP bindings", async () => {
     const channelId = "dm-1";
+    const boundSessionKey = "agent:codex:acp:binding:discord:default:dmfeedface";
     const cfg = {
       commands: {
         useAccessGroups: false,
@@ -465,13 +617,15 @@ describe("Discord native plugin command dispatch", () => {
     await expectBoundStatusCommandDispatch({
       cfg,
       interaction,
-      expectedPattern: /^agent:codex:acp:binding:discord:default:/,
+      channelId,
+      boundSessionKey,
     });
   });
 
   it("allows recovery commands through configured ACP bindings even when ensure fails", async () => {
     const guildId = "1459246755253325866";
     const channelId = "1479098716916023408";
+    const boundSessionKey = "agent:codex:acp:binding:discord:default:feedface";
     const cfg = {
       commands: {
         useAccessGroups: false,
@@ -497,13 +651,14 @@ describe("Discord native plugin command dispatch", () => {
       guildId,
       guildName: "Ops",
     });
-    const command = await createNativeCommand(cfg, {
+    const command = createNativeCommand(cfg, {
       name: "new",
       description: "Start a new session.",
       acceptsArgs: true,
     });
 
-    ensureConfiguredBindingRouteReadyMock.mockResolvedValue({
+    setConfiguredBinding(channelId, boundSessionKey);
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
       ok: false,
       error: "acpx exited with code 1",
     });
@@ -516,11 +671,10 @@ describe("Discord native plugin command dispatch", () => {
     const dispatchCall = dispatchSpy.mock.calls[0]?.[0] as {
       ctx?: { SessionKey?: string; CommandTargetSessionKey?: string };
     };
-    expect(dispatchCall.ctx?.SessionKey).toMatch(/^agent:codex:acp:binding:discord:default:/);
-    expect(dispatchCall.ctx?.CommandTargetSessionKey).toMatch(
-      /^agent:codex:acp:binding:discord:default:/,
-    );
-    expect(ensureConfiguredBindingRouteReadyMock).not.toHaveBeenCalled();
+    expect(dispatchCall.ctx?.SessionKey).toBe(boundSessionKey);
+    expect(dispatchCall.ctx?.CommandTargetSessionKey).toBe(boundSessionKey);
+    expect(persistentBindingMocks.resolveConfiguredAcpBindingRecord).toHaveBeenCalledTimes(1);
+    expect(persistentBindingMocks.ensureConfiguredAcpBindingSession).not.toHaveBeenCalled();
     expect(interaction.reply).not.toHaveBeenCalledWith(
       expect.objectContaining({
         content: "Configured ACP binding is unavailable right now. Please try again.",

extensions/discord/src/monitor/provider.test.ts

@@ -7,6 +7,7 @@ import {
   baseRuntime,
   getFirstDiscordMessageHandlerParams,
   getProviderMonitorTestMocks,
+  mockResolvedDiscordAccountConfig,
   resetDiscordProviderMonitorMocks,
 } from "../../../../test/helpers/extensions/discord-provider.test-support.js";
 
@@ -36,21 +37,6 @@ const {
   voiceRuntimeModuleLoadedMock,
 } = getProviderMonitorTestMocks();
 
-function createConfigWithDiscordAccount(overrides: Record<string, unknown> = {}): OpenClawConfig {
-  return {
-    channels: {
-      discord: {
-        accounts: {
-          default: {
-            token: "MTIz.abc.def",
-            ...overrides,
-          },
-        },
-      },
-    },
-  } as OpenClawConfig;
-}
-
 vi.mock("openclaw/plugin-sdk/plugin-runtime", async () => {
   const actual = await vi.importActual<typeof import("openclaw/plugin-sdk/plugin-runtime")>(
     "openclaw/plugin-sdk/plugin-runtime",
@@ -104,18 +90,7 @@ describe("monitorDiscordProvider", () => {
   };
 
   beforeEach(() => {
-    vi.resetModules();
     resetDiscordProviderMonitorMocks();
-    vi.doMock("../accounts.js", () => ({
-      resolveDiscordAccount: (...args: Parameters<typeof resolveDiscordAccountMock>) =>
-        resolveDiscordAccountMock(...args),
-    }));
-    vi.doMock("../probe.js", () => ({
-      fetchDiscordApplicationId: async () => "app-1",
-    }));
-    vi.doMock("../token.js", () => ({
-      normalizeDiscordToken: (value?: string) => value,
-    }));
   });
 
   it("stops thread bindings when startup fails before lifecycle begins", async () => {
@@ -164,7 +139,7 @@ describe("monitorDiscordProvider", () => {
   it("loads the Discord voice runtime only when voice is enabled", async () => {
     resolveDiscordAccountMock.mockReturnValue({
       accountId: "default",
-      token: "MTIz.abc.def",
+      token: "cfg-token",
       config: {
         commands: { native: true, nativeSkills: false },
         voice: { enabled: true },
@@ -381,19 +356,12 @@ describe("monitorDiscordProvider", () => {
   });
 
   it("forwards custom eventQueue config from discord config to Carbon Client", async () => {
-    resolveDiscordAccountMock.mockReturnValue({
-      accountId: "default",
-      token: "MTIz.abc.def",
-      config: {
-        commands: { native: true, nativeSkills: false },
-        voice: { enabled: false },
-        agentComponents: { enabled: false },
-        execApprovals: { enabled: false },
-        eventQueue: { listenerTimeout: 300_000 },
-      },
-    });
     const { monitorDiscordProvider } = await import("./provider.js");
 
+    mockResolvedDiscordAccountConfig({
+      eventQueue: { listenerTimeout: 300_000 },
+    });
+
     await monitorDiscordProvider({
       config: baseConfig(),
       runtime: baseRuntime(),
@@ -406,10 +374,12 @@ describe("monitorDiscordProvider", () => {
   it("does not reuse eventQueue.listenerTimeout as the queued inbound worker timeout", async () => {
     const { monitorDiscordProvider } = await import("./provider.js");
 
+    mockResolvedDiscordAccountConfig({
+      eventQueue: { listenerTimeout: 50_000 },
+    });
+
     await monitorDiscordProvider({
-      config: createConfigWithDiscordAccount({
-        eventQueue: { listenerTimeout: 50_000 },
-      }),
+      config: baseConfig(),
       runtime: baseRuntime(),
     });
 
@@ -422,19 +392,12 @@ describe("monitorDiscordProvider", () => {
   });
 
   it("forwards inbound worker timeout config to the Discord message handler", async () => {
-    resolveDiscordAccountMock.mockReturnValue({
-      accountId: "default",
-      token: "MTIz.abc.def",
-      config: {
-        commands: { native: true, nativeSkills: false },
-        voice: { enabled: false },
-        agentComponents: { enabled: false },
-        execApprovals: { enabled: false },
-        inboundWorker: { runTimeoutMs: 300_000 },
-      },
-    });
     const { monitorDiscordProvider } = await import("./provider.js");
 
+    mockResolvedDiscordAccountConfig({
+      inboundWorker: { runTimeoutMs: 300_000 },
+    });
+
     await monitorDiscordProvider({
       config: baseConfig(),
       runtime: baseRuntime(),

extensions/discord/src/runtime-api.ts

@@ -1,52 +0,0 @@
-export {
-  buildComputedAccountStatusSnapshot,
-  buildTokenChannelStatusSummary,
-  PAIRING_APPROVED_MESSAGE,
-  projectCredentialSnapshotFields,
-  resolveConfiguredFromCredentialStatuses,
-} from "openclaw/plugin-sdk/discord";
-export {
-  buildChannelConfigSchema,
-  getChatChannelMeta,
-  jsonResult,
-  readNumberParam,
-  readStringArrayParam,
-  readStringParam,
-  type ActionGate,
-  type ChannelPlugin,
-  type OpenClawConfig,
-} from "openclaw/plugin-sdk/discord-core";
-export { DiscordConfigSchema } from "openclaw/plugin-sdk/discord-core";
-export { readBooleanParam } from "openclaw/plugin-sdk/boolean-param";
-export {
-  listDiscordDirectoryGroupsFromConfig,
-  listDiscordDirectoryPeersFromConfig,
-} from "./directory-config.js";
-export {
-  createScopedAccountConfigAccessors,
-  createScopedChannelConfigBase,
-} from "openclaw/plugin-sdk/channel-config-helpers";
-export {
-  createAccountActionGate,
-  createAccountListHelpers,
-  DEFAULT_ACCOUNT_ID,
-  normalizeAccountId,
-  resolveAccountEntry,
-} from "openclaw/plugin-sdk/account-resolution";
-export type {
-  ChannelMessageActionAdapter,
-  ChannelMessageActionName,
-} from "openclaw/plugin-sdk/channel-runtime";
-export {
-  assertMediaNotDataUrl,
-  parseAvailableTags,
-  readReactionParams,
-  resolvePollMaxSelections,
-  withNormalizedTimestamp,
-} from "openclaw/plugin-sdk/discord-core";
-export type { DiscordAccountConfig, DiscordActionConfig } from "openclaw/plugin-sdk/discord";
-export {
-  hasConfiguredSecretInput,
-  normalizeResolvedSecretInputString,
-  normalizeSecretInputString,
-} from "openclaw/plugin-sdk/config-runtime";

extensions/discord/src/setup-core.ts

@@ -1,12 +1,12 @@
 import type { DiscordGuildEntry } from "openclaw/plugin-sdk/config-runtime";
 import {
-  createAccountScopedAllowFromSection,
-  createAccountScopedGroupAccessSection,
-  createLegacyCompatChannelDmPolicy,
   DEFAULT_ACCOUNT_ID,
   createEnvPatchedAccountSetupAdapter,
+  noteChannelLookupFailure,
+  noteChannelLookupSummary,
   parseMentionOrPrefixedId,
   patchChannelConfigForAccount,
+  setLegacyChannelDmPolicyWithAllowFrom,
   setSetupChannelEnabled,
   type OpenClawConfig,
 } from "openclaw/plugin-sdk/setup";
@@ -88,11 +88,21 @@ export function createDiscordSetupWizardBase(handlers: {
     NonNullable<NonNullable<ChannelSetupWizard["groupAccess"]>["resolveAllowlist"]>
   >;
 }) {
-  const discordDmPolicy: ChannelSetupDmPolicy = createLegacyCompatChannelDmPolicy({
+  const discordDmPolicy: ChannelSetupDmPolicy = {
     label: "Discord",
     channel,
+    policyKey: "channels.discord.dmPolicy",
+    allowFromKey: "channels.discord.allowFrom",
+    getCurrent: (cfg: OpenClawConfig) =>
+      cfg.channels?.discord?.dmPolicy ?? cfg.channels?.discord?.dm?.policy ?? "pairing",
+    setPolicy: (cfg: OpenClawConfig, policy) =>
+      setLegacyChannelDmPolicyWithAllowFrom({
+        cfg,
+        channel,
+        dmPolicy: policy,
+      }),
     promptAllowFrom: handlers.promptAllowFrom,
-  });
+  };
 
   return {
     channel,
@@ -135,8 +145,7 @@ export function createDiscordSetupWizardBase(handlers: {
         },
       },
     ],
-    groupAccess: createAccountScopedGroupAccessSection({
-      channel,
+    groupAccess: {
       label: "Discord channels",
       placeholder: "My Server/#general, guildId/channelId, #support",
       currentPolicy: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) =>
@@ -155,8 +164,57 @@ export function createDiscordSetupWizardBase(handlers: {
         ),
       updatePrompt: ({ cfg, accountId }: { cfg: OpenClawConfig; accountId: string }) =>
         Boolean(resolveDiscordAccount({ cfg, accountId }).config.guilds),
-      resolveAllowlist: handlers.resolveGroupAllowlist,
-      fallbackResolved: (entries) => entries.map((input) => ({ input, resolved: false })),
+      setPolicy: ({
+        cfg,
+        accountId,
+        policy,
+      }: {
+        cfg: OpenClawConfig;
+        accountId: string;
+        policy: "open" | "allowlist" | "disabled";
+      }) =>
+        patchChannelConfigForAccount({
+          cfg,
+          channel,
+          accountId,
+          patch: { groupPolicy: policy },
+        }),
+      resolveAllowlist: async ({
+        cfg,
+        accountId,
+        credentialValues,
+        entries,
+        prompter,
+      }: {
+        cfg: OpenClawConfig;
+        accountId: string;
+        credentialValues: { token?: string };
+        entries: string[];
+        prompter: { note: (message: string, title?: string) => Promise<void> };
+      }) => {
+        try {
+          return await handlers.resolveGroupAllowlist({
+            cfg,
+            accountId,
+            credentialValues,
+            entries,
+            prompter,
+          });
+        } catch (error) {
+          await noteChannelLookupFailure({
+            prompter,
+            label: "Discord channels",
+            error,
+          });
+          await noteChannelLookupSummary({
+            prompter,
+            label: "Discord channels",
+            resolvedSections: [],
+            unresolved: entries,
+          });
+          return entries.map((input) => ({ input, resolved: false }));
+        }
+      },
       applyAllowlist: ({
         cfg,
         accountId,
@@ -166,9 +224,8 @@ export function createDiscordSetupWizardBase(handlers: {
         accountId: string;
         resolved: unknown;
       }) => setDiscordGuildChannelAllowlist(cfg, accountId, resolved as never),
-    }),
-    allowFrom: createAccountScopedAllowFromSection({
-      channel,
+    },
+    allowFrom: {
       credentialInputKey: "token",
       helpTitle: "Discord allowlist",
       helpLines: [
@@ -185,15 +242,42 @@ export function createDiscordSetupWizardBase(handlers: {
       invalidWithoutCredentialNote:
         "Bot token missing; use numeric user ids (or mention form) only.",
       parseId: parseDiscordAllowFromId,
-      resolveEntries: handlers.resolveAllowFromEntries,
-    }),
+      resolveEntries: async ({
+        cfg,
+        accountId,
+        credentialValues,
+        entries,
+      }: {
+        cfg: OpenClawConfig;
+        accountId: string;
+        credentialValues: { token?: string };
+        entries: string[];
+      }) => await handlers.resolveAllowFromEntries({ cfg, accountId, credentialValues, entries }),
+      apply: async ({
+        cfg,
+        accountId,
+        allowFrom,
+      }: {
+        cfg: OpenClawConfig;
+        accountId: string;
+        allowFrom: string[];
+      }) =>
+        patchChannelConfigForAccount({
+          cfg,
+          channel,
+          accountId,
+          patch: { dmPolicy: "allowlist", allowFrom },
+        }),
+    },
     dmPolicy: discordDmPolicy,
     disable: (cfg: OpenClawConfig) => setSetupChannelEnabled(cfg, channel, false),
   } satisfies ChannelSetupWizard;
 }
-export function createDiscordSetupWizardProxy(loadWizard: () => Promise<ChannelSetupWizard>) {
+export function createDiscordSetupWizardProxy(
+  loadWizard: () => Promise<{ discordSetupWizard: ChannelSetupWizard }>,
+) {
   return createAllowlistSetupWizardProxy({
-    loadWizard,
+    loadWizard: async () => (await loadWizard()).discordSetupWizard,
     createBase: createDiscordSetupWizardBase,
     fallbackResolvedGroupAllowlist: (entries) =>
       entries.map((input) => ({ input, resolved: false })),

extensions/discord/src/setup-surface.ts

@@ -1,13 +1,17 @@
 import {
-  resolveEntriesWithOptionalToken,
   type OpenClawConfig,
-  promptLegacyChannelAllowFromForAccount,
+  promptLegacyChannelAllowFrom,
+  resolveSetupAccountId,
   type WizardPrompter,
 } from "openclaw/plugin-sdk/setup";
 import { type ChannelSetupWizard } from "openclaw/plugin-sdk/setup";
 import { formatDocsLink } from "openclaw/plugin-sdk/setup-tools";
 import { resolveDefaultDiscordAccountId, resolveDiscordAccount } from "./accounts.js";
-import { resolveDiscordChannelAllowlist } from "./resolve-channels.js";
+import { normalizeDiscordSlug } from "./monitor/allow-list.js";
+import {
+  resolveDiscordChannelAllowlist,
+  type DiscordChannelResolution,
+} from "./resolve-channels.js";
 import { resolveDiscordUserAllowlist } from "./resolve-users.js";
 import {
   createDiscordSetupWizardBase,
@@ -19,26 +23,22 @@ import {
 const channel = "discord" as const;
 
 async function resolveDiscordAllowFromEntries(params: { token?: string; entries: string[] }) {
-  return await resolveEntriesWithOptionalToken({
-    token: params.token,
-    entries: params.entries,
-    buildWithoutToken: (input) => ({
+  if (!params.token?.trim()) {
+    return params.entries.map((input) => ({
       input,
       resolved: false,
       id: null,
-    }),
-    resolveEntries: async ({ token, entries }) =>
-      (
-        await resolveDiscordUserAllowlist({
-          token,
-          entries,
-        })
-      ).map((entry) => ({
-        input: entry.input,
-        resolved: entry.resolved,
-        id: entry.id ?? null,
-      })),
+    }));
+  }
+  const resolved = await resolveDiscordUserAllowlist({
+    token: params.token,
+    entries: params.entries,
   });
+  return resolved.map((entry) => ({
+    input: entry.input,
+    resolved: entry.resolved,
+    id: entry.id ?? null,
+  }));
 }
 
 async function promptDiscordAllowFrom(params: {
@@ -46,15 +46,17 @@ async function promptDiscordAllowFrom(params: {
   prompter: WizardPrompter;
   accountId?: string;
 }): Promise<OpenClawConfig> {
-  return await promptLegacyChannelAllowFromForAccount({
+  const accountId = resolveSetupAccountId({
+    accountId: params.accountId,
+    defaultAccountId: resolveDefaultDiscordAccountId(params.cfg),
+  });
+  const resolved = resolveDiscordAccount({ cfg: params.cfg, accountId });
+  return promptLegacyChannelAllowFrom({
     cfg: params.cfg,
     channel,
     prompter: params.prompter,
-    accountId: params.accountId,
-    defaultAccountId: resolveDefaultDiscordAccountId(params.cfg),
-    resolveAccount: (cfg, accountId) => resolveDiscordAccount({ cfg, accountId }),
-    resolveExisting: (account) => account.config.allowFrom ?? account.config.dm?.allowFrom ?? [],
-    resolveToken: (account) => account.token,
+    existing: resolved.config.allowFrom ?? resolved.config.dm?.allowFrom ?? [],
+    token: resolved.token,
     noteTitle: "Discord allowlist",
     noteLines: [
       "Allowlist Discord DMs by username (we resolve to user ids).",
@@ -69,17 +71,11 @@ async function promptDiscordAllowFrom(params: {
     placeholder: "@alice, 123456789012345678",
     parseId: parseDiscordAllowFromId,
     invalidWithoutTokenNote: "Bot token missing; use numeric user ids (or mention form) only.",
-    resolveEntries: async ({ token, entries }) =>
-      (
-        await resolveDiscordUserAllowlist({
-          token,
-          entries,
-        })
-      ).map((entry) => ({
-        input: entry.input,
-        resolved: entry.resolved,
-        id: entry.id ?? null,
-      })),
+    resolveEntries: ({ token, entries }) =>
+      resolveDiscordUserAllowlist({
+        token,
+        entries,
+      }),
   });
 }
 
@@ -89,20 +85,18 @@ async function resolveDiscordGroupAllowlist(params: {
   credentialValues: { token?: string };
   entries: string[];
 }) {
-  return await resolveEntriesWithOptionalToken({
-    token:
-      resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId }).token ||
-      (typeof params.credentialValues.token === "string" ? params.credentialValues.token : ""),
-    entries: params.entries,
-    buildWithoutToken: (input) => ({
+  const token =
+    resolveDiscordAccount({ cfg: params.cfg, accountId: params.accountId }).token ||
+    (typeof params.credentialValues.token === "string" ? params.credentialValues.token : "");
+  if (!token || params.entries.length === 0) {
+    return params.entries.map((input) => ({
       input,
       resolved: false,
-    }),
-    resolveEntries: async ({ token, entries }) =>
-      await resolveDiscordChannelAllowlist({
-        token,
-        entries,
-      }),
+    }));
+  }
+  return await resolveDiscordChannelAllowlist({
+    token,
+    entries: params.entries,
   });
 }
 

extensions/discord/src/shared.ts

@@ -1,5 +1,14 @@
 import { formatAllowFromLowercase } from "openclaw/plugin-sdk/allow-from";
-import { createChannelPluginBase } from "openclaw/plugin-sdk/core";
+import {
+  createScopedAccountConfigAccessors,
+  createScopedChannelConfigBase,
+} from "openclaw/plugin-sdk/channel-config-helpers";
+import {
+  buildChannelConfigSchema,
+  DiscordConfigSchema,
+  getChatChannelMeta,
+  type ChannelPlugin,
+} from "openclaw/plugin-sdk/discord-core";
 import { inspectDiscordAccount } from "./account-inspect.js";
 import {
   listDiscordAccountIds,
@@ -7,14 +16,6 @@ import {
   resolveDiscordAccount,
   type ResolvedDiscordAccount,
 } from "./accounts.js";
-import {
-  createScopedAccountConfigAccessors,
-  createScopedChannelConfigBase,
-  buildChannelConfigSchema,
-  DiscordConfigSchema,
-  getChatChannelMeta,
-  type ChannelPlugin,
-} from "./runtime-api.js";
 import { createDiscordSetupWizardProxy } from "./setup-core.js";
 
 export const DISCORD_CHANNEL = "discord" as const;
@@ -23,9 +24,9 @@ async function loadDiscordChannelRuntime() {
   return await import("./channel.runtime.js");
 }
 
-export const discordSetupWizard = createDiscordSetupWizardProxy(
-  async () => (await loadDiscordChannelRuntime()).discordSetupWizard,
-);
+export const discordSetupWizard = createDiscordSetupWizardProxy(async () => ({
+  discordSetupWizard: (await loadDiscordChannelRuntime()).discordSetupWizard,
+}));
 
 export const discordConfigAccessors = createScopedAccountConfigAccessors({
   resolveAccount: ({ cfg, accountId }) => resolveDiscordAccount({ cfg, accountId }),
@@ -57,10 +58,12 @@ export function createDiscordPluginBase(params: {
   | "config"
   | "setup"
 > {
-  return createChannelPluginBase({
+  return {
     id: DISCORD_CHANNEL,
+    meta: {
+      ...getChatChannelMeta(DISCORD_CHANNEL),
+    },
     setupWizard: discordSetupWizard,
-    meta: { ...getChatChannelMeta(DISCORD_CHANNEL) },
     capabilities: {
       chatTypes: ["direct", "channel", "thread"],
       polls: true,
@@ -87,16 +90,5 @@ export function createDiscordPluginBase(params: {
       ...discordConfigAccessors,
     },
     setup: params.setup,
-  }) as Pick<
-    ChannelPlugin<ResolvedDiscordAccount>,
-    | "id"
-    | "meta"
-    | "setupWizard"
-    | "capabilities"
-    | "streaming"
-    | "reload"
-    | "configSchema"
-    | "config"
-    | "setup"
-  >;
+  };
 }

extensions/fal/index.ts

@@ -1,44 +0,0 @@
-import { definePluginEntry } from "openclaw/plugin-sdk/core";
-import { buildFalImageGenerationProvider } from "openclaw/plugin-sdk/image-generation";
-import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
-import { applyFalConfig, FAL_DEFAULT_IMAGE_MODEL_REF } from "./onboard.js";
-
-const PROVIDER_ID = "fal";
-
-export default definePluginEntry({
-  id: PROVIDER_ID,
-  name: "fal Provider",
-  description: "Bundled fal image generation provider",
-  register(api) {
-    api.registerProvider({
-      id: PROVIDER_ID,
-      label: "fal",
-      docsPath: "/providers/models",
-      envVars: ["FAL_KEY"],
-      auth: [
-        createProviderApiKeyAuthMethod({
-          providerId: PROVIDER_ID,
-          methodId: "api-key",
-          label: "fal API key",
-          hint: "Image generation API key",
-          optionKey: "falApiKey",
-          flagName: "--fal-api-key",
-          envVar: "FAL_KEY",
-          promptMessage: "Enter fal API key",
-          defaultModel: FAL_DEFAULT_IMAGE_MODEL_REF,
-          expectedProviders: ["fal"],
-          applyConfig: (cfg) => applyFalConfig(cfg),
-          wizard: {
-            choiceId: "fal-api-key",
-            choiceLabel: "fal API key",
-            choiceHint: "Image generation API key",
-            groupId: "fal",
-            groupLabel: "fal",
-            groupHint: "Image generation",
-          },
-        }),
-      ],
-    });
-    api.registerImageGenerationProvider(buildFalImageGenerationProvider());
-  },
-});

extensions/fal/onboard.ts

@@ -1,21 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/provider-onboard";
-
-export const FAL_DEFAULT_IMAGE_MODEL_REF = "fal/fal-ai/flux/dev";
-
-export function applyFalConfig(cfg: OpenClawConfig): OpenClawConfig {
-  if (cfg.agents?.defaults?.imageGenerationModel) {
-    return cfg;
-  }
-  return {
-    ...cfg,
-    agents: {
-      ...cfg.agents,
-      defaults: {
-        ...cfg.agents?.defaults,
-        imageGenerationModel: {
-          primary: FAL_DEFAULT_IMAGE_MODEL_REF,
-        },
-      },
-    },
-  };
-}

extensions/fal/openclaw.plugin.json

@@ -1,27 +0,0 @@
-{
-  "id": "fal",
-  "providers": ["fal"],
-  "providerAuthEnvVars": {
-    "fal": ["FAL_KEY"]
-  },
-  "providerAuthChoices": [
-    {
-      "provider": "fal",
-      "method": "api-key",
-      "choiceId": "fal-api-key",
-      "choiceLabel": "fal API key",
-      "groupId": "fal",
-      "groupLabel": "fal",
-      "groupHint": "Image generation",
-      "optionKey": "falApiKey",
-      "cliFlag": "--fal-api-key",
-      "cliOption": "--fal-api-key <key>",
-      "cliDescription": "fal API key"
-    }
-  ],
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {}
-  }
-}

extensions/fal/package.json

@@ -1,12 +0,0 @@
-{
-  "name": "@openclaw/fal-provider",
-  "version": "2026.3.14",
-  "private": true,
-  "description": "OpenClaw fal provider plugin",
-  "type": "module",
-  "openclaw": {
-    "extensions": [
-      "./index.ts"
-    ]
-  }
-}

extensions/feishu/runtime-api.ts

@@ -1 +0,0 @@
-export * from "openclaw/plugin-sdk/feishu";

extensions/feishu/src/accounts.ts

@@ -1,5 +1,5 @@
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "openclaw/plugin-sdk/account-id";
-import type { ClawdbotConfig } from "../runtime-api.js";
+import type { ClawdbotConfig } from "openclaw/plugin-sdk/feishu";
 import { normalizeResolvedSecretInputString, normalizeSecretInputString } from "./secret-input.js";
 import type {
   FeishuConfig,

extensions/feishu/src/bitable.ts

@@ -1,6 +1,6 @@
 import type * as Lark from "@larksuiteoapi/node-sdk";
 import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginApi } from "../runtime-api.js";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/feishu";
 import { listEnabledFeishuAccounts } from "./accounts.js";
 import { createFeishuToolClient } from "./tool-account.js";
 

extensions/feishu/src/bot-content.ts

@@ -1,471 +0,0 @@
-import type { ClawdbotConfig } from "../runtime-api.js";
-import { normalizeFeishuExternalKey } from "./external-keys.js";
-import { downloadMessageResourceFeishu } from "./media.js";
-import { parsePostContent } from "./post.js";
-import { getFeishuRuntime } from "./runtime.js";
-import type { FeishuMediaInfo } from "./types.js";
-
-export type FeishuMention = {
-  key: string;
-  id: {
-    open_id?: string;
-    user_id?: string;
-    union_id?: string;
-  };
-  name: string;
-  tenant_key?: string;
-};
-
-type FeishuMessageLike = {
-  message: {
-    content: string;
-    message_type: string;
-    mentions?: FeishuMention[];
-    chat_id: string;
-    root_id?: string;
-    parent_id?: string;
-    thread_id?: string;
-    message_id: string;
-  };
-  sender: {
-    sender_id: {
-      open_id?: string;
-      user_id?: string;
-    };
-  };
-};
-
-export type GroupSessionScope = "group" | "group_sender" | "group_topic" | "group_topic_sender";
-
-export type ResolvedFeishuGroupSession = {
-  peerId: string;
-  parentPeer: { kind: "group"; id: string } | null;
-  groupSessionScope: GroupSessionScope;
-  replyInThread: boolean;
-  threadReply: boolean;
-};
-
-function buildFeishuConversationId(params: {
-  chatId: string;
-  scope: GroupSessionScope | "group_sender";
-  topicId?: string;
-  senderOpenId?: string;
-}): string {
-  switch (params.scope) {
-    case "group_sender":
-      return `${params.chatId}:sender:${params.senderOpenId}`;
-    case "group_topic":
-      return `${params.chatId}:topic:${params.topicId}`;
-    case "group_topic_sender":
-      return `${params.chatId}:topic:${params.topicId}:sender:${params.senderOpenId}`;
-    default:
-      return params.chatId;
-  }
-}
-
-export function resolveFeishuGroupSession(params: {
-  chatId: string;
-  senderOpenId: string;
-  messageId: string;
-  rootId?: string;
-  threadId?: string;
-  groupConfig?: {
-    groupSessionScope?: GroupSessionScope;
-    topicSessionMode?: "enabled" | "disabled";
-    replyInThread?: "enabled" | "disabled";
-  };
-  feishuCfg?: {
-    groupSessionScope?: GroupSessionScope;
-    topicSessionMode?: "enabled" | "disabled";
-    replyInThread?: "enabled" | "disabled";
-  };
-}): ResolvedFeishuGroupSession {
-  const { chatId, senderOpenId, messageId, rootId, threadId, groupConfig, feishuCfg } = params;
-  const normalizedThreadId = threadId?.trim();
-  const normalizedRootId = rootId?.trim();
-  const threadReply = Boolean(normalizedThreadId || normalizedRootId);
-  const replyInThread =
-    (groupConfig?.replyInThread ?? feishuCfg?.replyInThread ?? "disabled") === "enabled" ||
-    threadReply;
-  const legacyTopicSessionMode =
-    groupConfig?.topicSessionMode ?? feishuCfg?.topicSessionMode ?? "disabled";
-  const groupSessionScope: GroupSessionScope =
-    groupConfig?.groupSessionScope ??
-    feishuCfg?.groupSessionScope ??
-    (legacyTopicSessionMode === "enabled" ? "group_topic" : "group");
-  const topicScope =
-    groupSessionScope === "group_topic" || groupSessionScope === "group_topic_sender"
-      ? (normalizedRootId ?? normalizedThreadId ?? (replyInThread ? messageId : null))
-      : null;
-
-  let peerId = chatId;
-  switch (groupSessionScope) {
-    case "group_sender":
-      peerId = buildFeishuConversationId({ chatId, scope: "group_sender", senderOpenId });
-      break;
-    case "group_topic":
-      peerId = topicScope
-        ? buildFeishuConversationId({ chatId, scope: "group_topic", topicId: topicScope })
-        : chatId;
-      break;
-    case "group_topic_sender":
-      peerId = topicScope
-        ? buildFeishuConversationId({
-            chatId,
-            scope: "group_topic_sender",
-            topicId: topicScope,
-            senderOpenId,
-          })
-        : buildFeishuConversationId({ chatId, scope: "group_sender", senderOpenId });
-      break;
-    case "group":
-    default:
-      peerId = chatId;
-      break;
-  }
-
-  return {
-    peerId,
-    parentPeer:
-      topicScope &&
-      (groupSessionScope === "group_topic" || groupSessionScope === "group_topic_sender")
-        ? { kind: "group", id: chatId }
-        : null,
-    groupSessionScope,
-    replyInThread,
-    threadReply,
-  };
-}
-
-export function parseMessageContent(content: string, messageType: string): string {
-  if (messageType === "post") {
-    return parsePostContent(content).textContent;
-  }
-
-  try {
-    const parsed = JSON.parse(content);
-    if (messageType === "text") {
-      return parsed.text || "";
-    }
-    if (messageType === "share_chat") {
-      if (parsed && typeof parsed === "object") {
-        const share = parsed as { body?: unknown; summary?: unknown; share_chat_id?: unknown };
-        if (typeof share.body === "string" && share.body.trim()) {
-          return share.body.trim();
-        }
-        if (typeof share.summary === "string" && share.summary.trim()) {
-          return share.summary.trim();
-        }
-        if (typeof share.share_chat_id === "string" && share.share_chat_id.trim()) {
-          return `[Forwarded message: ${share.share_chat_id.trim()}]`;
-        }
-      }
-      return "[Forwarded message]";
-    }
-    if (messageType === "merge_forward") {
-      return "[Merged and Forwarded Message - loading...]";
-    }
-    return content;
-  } catch {
-    return content;
-  }
-}
-
-function formatSubMessageContent(content: string, contentType: string): string {
-  try {
-    const parsed = JSON.parse(content);
-    switch (contentType) {
-      case "text":
-        return parsed.text || content;
-      case "post":
-        return parsePostContent(content).textContent;
-      case "image":
-        return "[Image]";
-      case "file":
-        return `[File: ${parsed.file_name || "unknown"}]`;
-      case "audio":
-        return "[Audio]";
-      case "video":
-        return "[Video]";
-      case "sticker":
-        return "[Sticker]";
-      case "merge_forward":
-        return "[Nested Merged Forward]";
-      default:
-        return `[${contentType}]`;
-    }
-  } catch {
-    return content;
-  }
-}
-
-export function parseMergeForwardContent(params: {
-  content: string;
-  log?: (...args: any[]) => void;
-}): string {
-  const { content, log } = params;
-  const maxMessages = 50;
-  log?.("feishu: parsing merge_forward sub-messages from API response");
-
-  let items: Array<{
-    message_id?: string;
-    msg_type?: string;
-    body?: { content?: string };
-    sender?: { id?: string };
-    upper_message_id?: string;
-    create_time?: string;
-  }>;
-  try {
-    items = JSON.parse(content);
-  } catch {
-    log?.("feishu: merge_forward items parse failed");
-    return "[Merged and Forwarded Message - parse error]";
-  }
-  if (!Array.isArray(items) || items.length === 0) {
-    return "[Merged and Forwarded Message - no sub-messages]";
-  }
-  const subMessages = items.filter((item) => item.upper_message_id);
-  if (subMessages.length === 0) {
-    return "[Merged and Forwarded Message - no sub-messages found]";
-  }
-
-  log?.(`feishu: merge_forward contains ${subMessages.length} sub-messages`);
-  subMessages.sort(
-    (a, b) => parseInt(a.create_time || "0", 10) - parseInt(b.create_time || "0", 10),
-  );
-
-  const lines = ["[Merged and Forwarded Messages]"];
-  for (const item of subMessages.slice(0, maxMessages)) {
-    lines.push(`- ${formatSubMessageContent(item.body?.content || "", item.msg_type || "text")}`);
-  }
-  if (subMessages.length > maxMessages) {
-    lines.push(`... and ${subMessages.length - maxMessages} more messages`);
-  }
-  return lines.join("\n");
-}
-
-export function checkBotMentioned(event: FeishuMessageLike, botOpenId?: string): boolean {
-  if (!botOpenId) {
-    return false;
-  }
-  if ((event.message.content ?? "").includes("@_all")) {
-    return true;
-  }
-  const mentions = event.message.mentions ?? [];
-  if (mentions.length > 0) {
-    return mentions.some((mention) => mention.id.open_id === botOpenId);
-  }
-  if (event.message.message_type === "post") {
-    return parsePostContent(event.message.content).mentionedOpenIds.some((id) => id === botOpenId);
-  }
-  return false;
-}
-
-export function normalizeMentions(
-  text: string,
-  mentions?: FeishuMention[],
-  botStripId?: string,
-): string {
-  if (!mentions || mentions.length === 0) {
-    return text;
-  }
-  const escaped = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const escapeName = (value: string) => value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
-  let result = text;
-  for (const mention of mentions) {
-    const mentionId = mention.id.open_id;
-    const replacement =
-      botStripId && mentionId === botStripId
-        ? ""
-        : mentionId
-          ? `<at user_id="${mentionId}">${escapeName(mention.name)}</at>`
-          : `@${mention.name}`;
-    result = result.replace(new RegExp(escaped(mention.key), "g"), () => replacement).trim();
-  }
-  return result;
-}
-
-export function normalizeFeishuCommandProbeBody(text: string): string {
-  if (!text) {
-    return "";
-  }
-  return text
-    .replace(/<at\b[^>]*>[^<]*<\/at>/giu, " ")
-    .replace(/(^|\s)@[^/\s]+(?=\s|$|\/)/gu, "$1")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-export function parseMediaKeys(
-  content: string,
-  messageType: string,
-): { imageKey?: string; fileKey?: string; fileName?: string } {
-  try {
-    const parsed = JSON.parse(content);
-    const imageKey = normalizeFeishuExternalKey(parsed.image_key);
-    const fileKey = normalizeFeishuExternalKey(parsed.file_key);
-    switch (messageType) {
-      case "image":
-        return { imageKey, fileName: parsed.file_name };
-      case "file":
-      case "audio":
-      case "sticker":
-        return { fileKey, fileName: parsed.file_name };
-      case "video":
-      case "media":
-        return { fileKey, imageKey, fileName: parsed.file_name };
-      default:
-        return {};
-    }
-  } catch {
-    return {};
-  }
-}
-
-export function toMessageResourceType(messageType: string): "image" | "file" {
-  return messageType === "image" ? "image" : "file";
-}
-
-function inferPlaceholder(messageType: string): string {
-  switch (messageType) {
-    case "image":
-      return "<media:image>";
-    case "file":
-      return "<media:document>";
-    case "audio":
-      return "<media:audio>";
-    case "video":
-    case "media":
-      return "<media:video>";
-    case "sticker":
-      return "<media:sticker>";
-    default:
-      return "<media:document>";
-  }
-}
-
-export async function resolveFeishuMediaList(params: {
-  cfg: ClawdbotConfig;
-  messageId: string;
-  messageType: string;
-  content: string;
-  maxBytes: number;
-  log?: (msg: string) => void;
-  accountId?: string;
-}): Promise<FeishuMediaInfo[]> {
-  const { cfg, messageId, messageType, content, maxBytes, log, accountId } = params;
-  const mediaTypes = ["image", "file", "audio", "video", "media", "sticker", "post"];
-  if (!mediaTypes.includes(messageType)) {
-    return [];
-  }
-
-  const out: FeishuMediaInfo[] = [];
-  const core = getFeishuRuntime();
-
-  if (messageType === "post") {
-    const { imageKeys, mediaKeys } = parsePostContent(content);
-    if (imageKeys.length === 0 && mediaKeys.length === 0) {
-      return [];
-    }
-    if (imageKeys.length > 0) {
-      log?.(`feishu: post message contains ${imageKeys.length} embedded image(s)`);
-    }
-    if (mediaKeys.length > 0) {
-      log?.(`feishu: post message contains ${mediaKeys.length} embedded media file(s)`);
-    }
-
-    for (const imageKey of imageKeys) {
-      try {
-        const result = await downloadMessageResourceFeishu({
-          cfg,
-          messageId,
-          fileKey: imageKey,
-          type: "image",
-          accountId,
-        });
-        const contentType =
-          result.contentType ?? (await core.media.detectMime({ buffer: result.buffer }));
-        const saved = await core.channel.media.saveMediaBuffer(
-          result.buffer,
-          contentType,
-          "inbound",
-          maxBytes,
-        );
-        out.push({
-          path: saved.path,
-          contentType: saved.contentType,
-          placeholder: "<media:image>",
-        });
-        log?.(`feishu: downloaded embedded image ${imageKey}, saved to ${saved.path}`);
-      } catch (err) {
-        log?.(`feishu: failed to download embedded image ${imageKey}: ${String(err)}`);
-      }
-    }
-
-    for (const media of mediaKeys) {
-      try {
-        const result = await downloadMessageResourceFeishu({
-          cfg,
-          messageId,
-          fileKey: media.fileKey,
-          type: "file",
-          accountId,
-        });
-        const contentType =
-          result.contentType ?? (await core.media.detectMime({ buffer: result.buffer }));
-        const saved = await core.channel.media.saveMediaBuffer(
-          result.buffer,
-          contentType,
-          "inbound",
-          maxBytes,
-        );
-        out.push({
-          path: saved.path,
-          contentType: saved.contentType,
-          placeholder: "<media:video>",
-        });
-        log?.(`feishu: downloaded embedded media ${media.fileKey}, saved to ${saved.path}`);
-      } catch (err) {
-        log?.(`feishu: failed to download embedded media ${media.fileKey}: ${String(err)}`);
-      }
-    }
-    return out;
-  }
-
-  const mediaKeys = parseMediaKeys(content, messageType);
-  if (!mediaKeys.imageKey && !mediaKeys.fileKey) {
-    return [];
-  }
-
-  try {
-    const fileKey = mediaKeys.fileKey || mediaKeys.imageKey;
-    if (!fileKey) {
-      return [];
-    }
-    const result = await downloadMessageResourceFeishu({
-      cfg,
-      messageId,
-      fileKey,
-      type: toMessageResourceType(messageType),
-      accountId,
-    });
-    const contentType =
-      result.contentType ?? (await core.media.detectMime({ buffer: result.buffer }));
-    const saved = await core.channel.media.saveMediaBuffer(
-      result.buffer,
-      contentType,
-      "inbound",
-      maxBytes,
-      result.fileName || mediaKeys.fileName,
-    );
-    out.push({
-      path: saved.path,
-      contentType: saved.contentType,
-      placeholder: inferPlaceholder(messageType),
-    });
-    log?.(`feishu: downloaded ${messageType} media, saved to ${saved.path}`);
-  } catch (err) {
-    log?.(`feishu: failed to download ${messageType} media: ${String(err)}`);
-  }
-  return out;
-}

extensions/feishu/src/bot-sender-name.ts

@@ -1,121 +0,0 @@
-import { createFeishuClient } from "./client.js";
-import type { ResolvedFeishuAccount } from "./types.js";
-
-export type FeishuPermissionError = {
-  code: number;
-  message: string;
-  grantUrl?: string;
-};
-
-type SenderNameResult = {
-  name?: string;
-  permissionError?: FeishuPermissionError;
-};
-
-const IGNORED_PERMISSION_SCOPE_TOKENS = ["contact:contact.base:readonly"];
-const FEISHU_SCOPE_CORRECTIONS: Record<string, string> = {
-  "contact:contact.base:readonly": "contact:user.base:readonly",
-};
-const SENDER_NAME_TTL_MS = 10 * 60 * 1000;
-const senderNameCache = new Map<string, { name: string; expireAt: number }>();
-
-function correctFeishuScopeInUrl(url: string): string {
-  let corrected = url;
-  for (const [wrong, right] of Object.entries(FEISHU_SCOPE_CORRECTIONS)) {
-    corrected = corrected.replaceAll(encodeURIComponent(wrong), encodeURIComponent(right));
-    corrected = corrected.replaceAll(wrong, right);
-  }
-  return corrected;
-}
-
-function shouldSuppressPermissionErrorNotice(permissionError: FeishuPermissionError): boolean {
-  const message = permissionError.message.toLowerCase();
-  return IGNORED_PERMISSION_SCOPE_TOKENS.some((token) => message.includes(token));
-}
-
-function extractPermissionError(err: unknown): FeishuPermissionError | null {
-  if (!err || typeof err !== "object") {
-    return null;
-  }
-  const axiosErr = err as { response?: { data?: unknown } };
-  const data = axiosErr.response?.data;
-  if (!data || typeof data !== "object") {
-    return null;
-  }
-  const feishuErr = data as { code?: number; msg?: string };
-  if (feishuErr.code !== 99991672) {
-    return null;
-  }
-  const msg = feishuErr.msg ?? "";
-  const urlMatch = msg.match(/https:\/\/[^\s,]+\/app\/[^\s,]+/);
-  return {
-    code: feishuErr.code,
-    message: msg,
-    grantUrl: urlMatch?.[0] ? correctFeishuScopeInUrl(urlMatch[0]) : undefined,
-  };
-}
-
-function resolveSenderLookupIdType(senderId: string): "open_id" | "user_id" | "union_id" {
-  const trimmed = senderId.trim();
-  if (trimmed.startsWith("ou_")) {
-    return "open_id";
-  }
-  if (trimmed.startsWith("on_")) {
-    return "union_id";
-  }
-  return "user_id";
-}
-
-export async function resolveFeishuSenderName(params: {
-  account: ResolvedFeishuAccount;
-  senderId: string;
-  log: (...args: any[]) => void;
-}): Promise<SenderNameResult> {
-  const { account, senderId, log } = params;
-  if (!account.configured) {
-    return {};
-  }
-
-  const normalizedSenderId = senderId.trim();
-  if (!normalizedSenderId) {
-    return {};
-  }
-
-  const cached = senderNameCache.get(normalizedSenderId);
-  const now = Date.now();
-  if (cached && cached.expireAt > now) {
-    return { name: cached.name };
-  }
-
-  try {
-    const client = createFeishuClient(account);
-    const userIdType = resolveSenderLookupIdType(normalizedSenderId);
-    const res: any = await client.contact.user.get({
-      path: { user_id: normalizedSenderId },
-      params: { user_id_type: userIdType },
-    });
-    const name: string | undefined =
-      res?.data?.user?.name ||
-      res?.data?.user?.display_name ||
-      res?.data?.user?.nickname ||
-      res?.data?.user?.en_name;
-
-    if (name && typeof name === "string") {
-      senderNameCache.set(normalizedSenderId, { name, expireAt: now + SENDER_NAME_TTL_MS });
-      return { name };
-    }
-    return {};
-  } catch (err) {
-    const permErr = extractPermissionError(err);
-    if (permErr) {
-      if (shouldSuppressPermissionErrorNotice(permErr)) {
-        log(`feishu: ignoring stale permission scope error: ${permErr.message}`);
-        return {};
-      }
-      log(`feishu: permission error resolving sender name: code=${permErr.code}`);
-      return { permissionError: permErr };
-    }
-    log(`feishu: failed to resolve sender name for ${normalizedSenderId}: ${String(err)}`);
-    return {};
-  }
-}

extensions/feishu/src/bot.ts

@@ -3,9 +3,7 @@ import {
   resolveConfiguredBindingRoute,
 } from "openclaw/plugin-sdk/conversation-runtime";
 import { getSessionBindingService } from "openclaw/plugin-sdk/conversation-runtime";
-import { deriveLastRoutePolicy } from "openclaw/plugin-sdk/routing";
-import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
-import type { ClawdbotConfig, RuntimeEnv } from "../runtime-api.js";
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk/feishu";
 import {
   buildAgentMediaPayload,
   buildPendingHistoryContextFromMap,
@@ -20,22 +18,16 @@ import {
   resolveOpenProviderRuntimeGroupPolicy,
   resolveDefaultGroupPolicy,
   warnMissingProviderGroupPolicyFallbackOnce,
-} from "../runtime-api.js";
+} from "openclaw/plugin-sdk/feishu";
+import { deriveLastRoutePolicy } from "openclaw/plugin-sdk/routing";
+import { resolveAgentIdFromSessionKey } from "openclaw/plugin-sdk/routing";
 import { resolveFeishuAccount } from "./accounts.js";
-import {
-  checkBotMentioned,
-  normalizeFeishuCommandProbeBody,
-  normalizeMentions,
-  parseMergeForwardContent,
-  parseMessageContent,
-  resolveFeishuGroupSession,
-  resolveFeishuMediaList,
-  toMessageResourceType,
-} from "./bot-content.js";
-import { type FeishuPermissionError, resolveFeishuSenderName } from "./bot-sender-name.js";
 import { createFeishuClient } from "./client.js";
+import { buildFeishuConversationId } from "./conversation-id.js";
 import { finalizeFeishuMessageProcessing, tryRecordMessagePersistent } from "./dedup.js";
 import { maybeCreateDynamicAgent } from "./dynamic-agent.js";
+import { normalizeFeishuExternalKey } from "./external-keys.js";
+import { downloadMessageResourceFeishu } from "./media.js";
 import { extractMentionTargets, isMentionForwardRequest } from "./mention.js";
 import {
   resolveFeishuGroupConfig,
@@ -43,18 +35,154 @@ import {
   resolveFeishuAllowlistMatch,
   isFeishuGroupAllowed,
 } from "./policy.js";
+import { parsePostContent } from "./post.js";
 import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
 import { getFeishuRuntime } from "./runtime.js";
 import { getMessageFeishu, listFeishuThreadMessages, sendMessageFeishu } from "./send.js";
-import type { FeishuMessageContext } from "./types.js";
+import type { FeishuMessageContext, FeishuMediaInfo, ResolvedFeishuAccount } from "./types.js";
 import type { DynamicAgentCreationConfig } from "./types.js";
 
-export { toMessageResourceType } from "./bot-content.js";
+// --- Permission error extraction ---
+// Extract permission grant URL from Feishu API error response.
+type PermissionError = {
+  code: number;
+  message: string;
+  grantUrl?: string;
+};
+
+const IGNORED_PERMISSION_SCOPE_TOKENS = ["contact:contact.base:readonly"];
+
+// Feishu API sometimes returns incorrect scope names in permission error
+// responses (e.g. "contact:contact.base:readonly" instead of the valid
+// "contact:user.base:readonly"). This map corrects known mismatches.
+const FEISHU_SCOPE_CORRECTIONS: Record<string, string> = {
+  "contact:contact.base:readonly": "contact:user.base:readonly",
+};
+
+function correctFeishuScopeInUrl(url: string): string {
+  let corrected = url;
+  for (const [wrong, right] of Object.entries(FEISHU_SCOPE_CORRECTIONS)) {
+    corrected = corrected.replaceAll(encodeURIComponent(wrong), encodeURIComponent(right));
+    corrected = corrected.replaceAll(wrong, right);
+  }
+  return corrected;
+}
+
+function shouldSuppressPermissionErrorNotice(permissionError: PermissionError): boolean {
+  const message = permissionError.message.toLowerCase();
+  return IGNORED_PERMISSION_SCOPE_TOKENS.some((token) => message.includes(token));
+}
+
+function extractPermissionError(err: unknown): PermissionError | null {
+  if (!err || typeof err !== "object") return null;
+
+  // Axios error structure: err.response.data contains the Feishu error
+  const axiosErr = err as { response?: { data?: unknown } };
+  const data = axiosErr.response?.data;
+  if (!data || typeof data !== "object") return null;
+
+  const feishuErr = data as {
+    code?: number;
+    msg?: string;
+    error?: { permission_violations?: Array<{ uri?: string }> };
+  };
+
+  // Feishu permission error code: 99991672
+  if (feishuErr.code !== 99991672) return null;
+
+  // Extract the grant URL from the error message (contains the direct link)
+  const msg = feishuErr.msg ?? "";
+  const urlMatch = msg.match(/https:\/\/[^\s,]+\/app\/[^\s,]+/);
+  const grantUrl = urlMatch?.[0] ? correctFeishuScopeInUrl(urlMatch[0]) : undefined;
+
+  return {
+    code: feishuErr.code,
+    message: msg,
+    grantUrl,
+  };
+}
+
+// --- Sender name resolution (so the agent can distinguish who is speaking in group chats) ---
+// Cache display names by sender id (open_id/user_id) to avoid an API call on every message.
+const SENDER_NAME_TTL_MS = 10 * 60 * 1000;
+const senderNameCache = new Map<string, { name: string; expireAt: number }>();
 
 // Cache permission errors to avoid spamming the user with repeated notifications.
 // Key: appId or "default", Value: timestamp of last notification
 const permissionErrorNotifiedAt = new Map<string, number>();
 const PERMISSION_ERROR_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+
+type SenderNameResult = {
+  name?: string;
+  permissionError?: PermissionError;
+};
+
+function resolveSenderLookupIdType(senderId: string): "open_id" | "user_id" | "union_id" {
+  const trimmed = senderId.trim();
+  if (trimmed.startsWith("ou_")) {
+    return "open_id";
+  }
+  if (trimmed.startsWith("on_")) {
+    return "union_id";
+  }
+  return "user_id";
+}
+
+async function resolveFeishuSenderName(params: {
+  account: ResolvedFeishuAccount;
+  senderId: string;
+  log: (...args: any[]) => void;
+}): Promise<SenderNameResult> {
+  const { account, senderId, log } = params;
+  if (!account.configured) return {};
+
+  const normalizedSenderId = senderId.trim();
+  if (!normalizedSenderId) return {};
+
+  const cached = senderNameCache.get(normalizedSenderId);
+  const now = Date.now();
+  if (cached && cached.expireAt > now) return { name: cached.name };
+
+  try {
+    const client = createFeishuClient(account);
+    const userIdType = resolveSenderLookupIdType(normalizedSenderId);
+
+    // contact/v3/users/:user_id?user_id_type=<open_id|user_id|union_id>
+    const res: any = await client.contact.user.get({
+      path: { user_id: normalizedSenderId },
+      params: { user_id_type: userIdType },
+    });
+
+    const name: string | undefined =
+      res?.data?.user?.name ||
+      res?.data?.user?.display_name ||
+      res?.data?.user?.nickname ||
+      res?.data?.user?.en_name;
+
+    if (name && typeof name === "string") {
+      senderNameCache.set(normalizedSenderId, { name, expireAt: now + SENDER_NAME_TTL_MS });
+      return { name };
+    }
+
+    return {};
+  } catch (err) {
+    // Check if this is a permission error
+    const permErr = extractPermissionError(err);
+    if (permErr) {
+      if (shouldSuppressPermissionErrorNotice(permErr)) {
+        log(`feishu: ignoring stale permission scope error: ${permErr.message}`);
+        return {};
+      }
+      log(`feishu: permission error resolving sender name: code=${permErr.code}`);
+      return { permissionError: permErr };
+    }
+
+    // Best-effort. Don't fail message handling if name lookup fails.
+    log(`feishu: failed to resolve sender name for ${normalizedSenderId}: ${String(err)}`);
+    return {};
+  }
+}
+
 export type FeishuMessageEvent = {
   sender: {
     sender_id: {
@@ -99,6 +227,546 @@ export type FeishuBotAddedEvent = {
   operator_tenant_key?: string;
 };
 
+type GroupSessionScope = "group" | "group_sender" | "group_topic" | "group_topic_sender";
+
+type ResolvedFeishuGroupSession = {
+  peerId: string;
+  parentPeer: { kind: "group"; id: string } | null;
+  groupSessionScope: GroupSessionScope;
+  replyInThread: boolean;
+  threadReply: boolean;
+};
+
+function resolveFeishuGroupSession(params: {
+  chatId: string;
+  senderOpenId: string;
+  messageId: string;
+  rootId?: string;
+  threadId?: string;
+  groupConfig?: {
+    groupSessionScope?: GroupSessionScope;
+    topicSessionMode?: "enabled" | "disabled";
+    replyInThread?: "enabled" | "disabled";
+  };
+  feishuCfg?: {
+    groupSessionScope?: GroupSessionScope;
+    topicSessionMode?: "enabled" | "disabled";
+    replyInThread?: "enabled" | "disabled";
+  };
+}): ResolvedFeishuGroupSession {
+  const { chatId, senderOpenId, messageId, rootId, threadId, groupConfig, feishuCfg } = params;
+
+  const normalizedThreadId = threadId?.trim();
+  const normalizedRootId = rootId?.trim();
+  const threadReply = Boolean(normalizedThreadId || normalizedRootId);
+  const replyInThread =
+    (groupConfig?.replyInThread ?? feishuCfg?.replyInThread ?? "disabled") === "enabled" ||
+    threadReply;
+
+  const legacyTopicSessionMode =
+    groupConfig?.topicSessionMode ?? feishuCfg?.topicSessionMode ?? "disabled";
+  const groupSessionScope: GroupSessionScope =
+    groupConfig?.groupSessionScope ??
+    feishuCfg?.groupSessionScope ??
+    (legacyTopicSessionMode === "enabled" ? "group_topic" : "group");
+
+  // Keep topic session keys stable across the "first turn creates thread" flow:
+  // first turn may only have message_id, while the next turn carries root_id/thread_id.
+  // Prefer root_id first so both turns stay on the same peer key.
+  const topicScope =
+    groupSessionScope === "group_topic" || groupSessionScope === "group_topic_sender"
+      ? (normalizedRootId ?? normalizedThreadId ?? (replyInThread ? messageId : null))
+      : null;
+
+  let peerId = chatId;
+  switch (groupSessionScope) {
+    case "group_sender":
+      peerId = buildFeishuConversationId({
+        chatId,
+        scope: "group_sender",
+        senderOpenId,
+      });
+      break;
+    case "group_topic":
+      peerId = topicScope
+        ? buildFeishuConversationId({
+            chatId,
+            scope: "group_topic",
+            topicId: topicScope,
+          })
+        : chatId;
+      break;
+    case "group_topic_sender":
+      peerId = topicScope
+        ? buildFeishuConversationId({
+            chatId,
+            scope: "group_topic_sender",
+            topicId: topicScope,
+            senderOpenId,
+          })
+        : buildFeishuConversationId({
+            chatId,
+            scope: "group_sender",
+            senderOpenId,
+          });
+      break;
+    case "group":
+    default:
+      peerId = chatId;
+      break;
+  }
+
+  const parentPeer =
+    topicScope &&
+    (groupSessionScope === "group_topic" || groupSessionScope === "group_topic_sender")
+      ? {
+          kind: "group" as const,
+          id: chatId,
+        }
+      : null;
+
+  return {
+    peerId,
+    parentPeer,
+    groupSessionScope,
+    replyInThread,
+    threadReply,
+  };
+}
+
+function parseMessageContent(content: string, messageType: string): string {
+  if (messageType === "post") {
+    // Extract text content from rich text post
+    const { textContent } = parsePostContent(content);
+    return textContent;
+  }
+
+  try {
+    const parsed = JSON.parse(content);
+    if (messageType === "text") {
+      return parsed.text || "";
+    }
+    if (messageType === "share_chat") {
+      // Preserve available summary text for merged/forwarded chat messages.
+      if (parsed && typeof parsed === "object") {
+        const share = parsed as {
+          body?: unknown;
+          summary?: unknown;
+          share_chat_id?: unknown;
+        };
+        if (typeof share.body === "string" && share.body.trim().length > 0) {
+          return share.body.trim();
+        }
+        if (typeof share.summary === "string" && share.summary.trim().length > 0) {
+          return share.summary.trim();
+        }
+        if (typeof share.share_chat_id === "string" && share.share_chat_id.trim().length > 0) {
+          return `[Forwarded message: ${share.share_chat_id.trim()}]`;
+        }
+      }
+      return "[Forwarded message]";
+    }
+    if (messageType === "merge_forward") {
+      // Return placeholder; actual content fetched asynchronously in handleFeishuMessage
+      return "[Merged and Forwarded Message - loading...]";
+    }
+    return content;
+  } catch {
+    return content;
+  }
+}
+
+/**
+ * Parse merge_forward message content and fetch sub-messages.
+ * Returns formatted text content of all sub-messages.
+ */
+function parseMergeForwardContent(params: {
+  content: string;
+  log?: (...args: any[]) => void;
+}): string {
+  const { content, log } = params;
+  const maxMessages = 50;
+
+  // For merge_forward, the API returns all sub-messages in items array
+  // with upper_message_id pointing to the merge_forward message.
+  // The 'content' parameter here is actually the full API response items array as JSON.
+  log?.(`feishu: parsing merge_forward sub-messages from API response`);
+
+  let items: Array<{
+    message_id?: string;
+    msg_type?: string;
+    body?: { content?: string };
+    sender?: { id?: string };
+    upper_message_id?: string;
+    create_time?: string;
+  }>;
+
+  try {
+    items = JSON.parse(content);
+  } catch {
+    log?.(`feishu: merge_forward items parse failed`);
+    return "[Merged and Forwarded Message - parse error]";
+  }
+
+  if (!Array.isArray(items) || items.length === 0) {
+    return "[Merged and Forwarded Message - no sub-messages]";
+  }
+
+  // Filter to only sub-messages (those with upper_message_id, skip the merge_forward container itself)
+  const subMessages = items.filter((item) => item.upper_message_id);
+
+  if (subMessages.length === 0) {
+    return "[Merged and Forwarded Message - no sub-messages found]";
+  }
+
+  log?.(`feishu: merge_forward contains ${subMessages.length} sub-messages`);
+
+  // Sort by create_time
+  subMessages.sort((a, b) => {
+    const timeA = parseInt(a.create_time || "0", 10);
+    const timeB = parseInt(b.create_time || "0", 10);
+    return timeA - timeB;
+  });
+
+  // Format output
+  const lines: string[] = ["[Merged and Forwarded Messages]"];
+  const limitedMessages = subMessages.slice(0, maxMessages);
+
+  for (const item of limitedMessages) {
+    const msgContent = item.body?.content || "";
+    const msgType = item.msg_type || "text";
+    const formatted = formatSubMessageContent(msgContent, msgType);
+    lines.push(`- ${formatted}`);
+  }
+
+  if (subMessages.length > maxMessages) {
+    lines.push(`... and ${subMessages.length - maxMessages} more messages`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format sub-message content based on message type.
+ */
+function formatSubMessageContent(content: string, contentType: string): string {
+  try {
+    const parsed = JSON.parse(content);
+    switch (contentType) {
+      case "text":
+        return parsed.text || content;
+      case "post": {
+        const { textContent } = parsePostContent(content);
+        return textContent;
+      }
+      case "image":
+        return "[Image]";
+      case "file":
+        return `[File: ${parsed.file_name || "unknown"}]`;
+      case "audio":
+        return "[Audio]";
+      case "video":
+        return "[Video]";
+      case "sticker":
+        return "[Sticker]";
+      case "merge_forward":
+        return "[Nested Merged Forward]";
+      default:
+        return `[${contentType}]`;
+    }
+  } catch {
+    return content;
+  }
+}
+
+function checkBotMentioned(event: FeishuMessageEvent, botOpenId?: string): boolean {
+  if (!botOpenId) return false;
+  // Check for @all (@_all in Feishu) — treat as mentioning every bot
+  const rawContent = event.message.content ?? "";
+  if (rawContent.includes("@_all")) return true;
+  const mentions = event.message.mentions ?? [];
+  if (mentions.length > 0) {
+    // Rely on Feishu mention IDs; display names can vary by alias/context.
+    return mentions.some((m) => m.id.open_id === botOpenId);
+  }
+  // Post (rich text) messages may have empty message.mentions when they contain docs/paste
+  if (event.message.message_type === "post") {
+    const { mentionedOpenIds } = parsePostContent(event.message.content);
+    return mentionedOpenIds.some((id) => id === botOpenId);
+  }
+  return false;
+}
+
+function normalizeMentions(
+  text: string,
+  mentions?: FeishuMessageEvent["message"]["mentions"],
+  botStripId?: string,
+): string {
+  if (!mentions || mentions.length === 0) return text;
+
+  const escaped = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapeName = (value: string) => value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  let result = text;
+
+  for (const mention of mentions) {
+    const mentionId = mention.id.open_id;
+    const replacement =
+      botStripId && mentionId === botStripId
+        ? ""
+        : mentionId
+          ? `<at user_id="${mentionId}">${escapeName(mention.name)}</at>`
+          : `@${mention.name}`;
+
+    result = result.replace(new RegExp(escaped(mention.key), "g"), () => replacement).trim();
+  }
+
+  return result;
+}
+
+function normalizeFeishuCommandProbeBody(text: string): string {
+  if (!text) {
+    return "";
+  }
+  return text
+    .replace(/<at\b[^>]*>[^<]*<\/at>/giu, " ")
+    .replace(/(^|\s)@[^/\s]+(?=\s|$|\/)/gu, "$1")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Parse media keys from message content based on message type.
+ */
+function parseMediaKeys(
+  content: string,
+  messageType: string,
+): {
+  imageKey?: string;
+  fileKey?: string;
+  fileName?: string;
+} {
+  try {
+    const parsed = JSON.parse(content);
+    const imageKey = normalizeFeishuExternalKey(parsed.image_key);
+    const fileKey = normalizeFeishuExternalKey(parsed.file_key);
+    switch (messageType) {
+      case "image":
+        return { imageKey, fileName: parsed.file_name };
+      case "file":
+        return { fileKey, fileName: parsed.file_name };
+      case "audio":
+        return { fileKey, fileName: parsed.file_name };
+      case "video":
+      case "media":
+        // Video/media has both file_key (video) and image_key (thumbnail)
+        return { fileKey, imageKey, fileName: parsed.file_name };
+      case "sticker":
+        return { fileKey, fileName: parsed.file_name };
+      default:
+        return {};
+    }
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Map Feishu message type to messageResource.get resource type.
+ * Feishu messageResource API supports only: image | file.
+ */
+export function toMessageResourceType(messageType: string): "image" | "file" {
+  return messageType === "image" ? "image" : "file";
+}
+
+/**
+ * Infer placeholder text based on message type.
+ */
+function inferPlaceholder(messageType: string): string {
+  switch (messageType) {
+    case "image":
+      return "<media:image>";
+    case "file":
+      return "<media:document>";
+    case "audio":
+      return "<media:audio>";
+    case "video":
+    case "media":
+      return "<media:video>";
+    case "sticker":
+      return "<media:sticker>";
+    default:
+      return "<media:document>";
+  }
+}
+
+/**
+ * Resolve media from a Feishu message, downloading and saving to disk.
+ * Similar to Discord's resolveMediaList().
+ */
+async function resolveFeishuMediaList(params: {
+  cfg: ClawdbotConfig;
+  messageId: string;
+  messageType: string;
+  content: string;
+  maxBytes: number;
+  log?: (msg: string) => void;
+  accountId?: string;
+}): Promise<FeishuMediaInfo[]> {
+  const { cfg, messageId, messageType, content, maxBytes, log, accountId } = params;
+
+  // Only process media message types (including post for embedded images)
+  const mediaTypes = ["image", "file", "audio", "video", "media", "sticker", "post"];
+  if (!mediaTypes.includes(messageType)) {
+    return [];
+  }
+
+  const out: FeishuMediaInfo[] = [];
+  const core = getFeishuRuntime();
+
+  // Handle post (rich text) messages with embedded images/media.
+  if (messageType === "post") {
+    const { imageKeys, mediaKeys: postMediaKeys } = parsePostContent(content);
+    if (imageKeys.length === 0 && postMediaKeys.length === 0) {
+      return [];
+    }
+
+    if (imageKeys.length > 0) {
+      log?.(`feishu: post message contains ${imageKeys.length} embedded image(s)`);
+    }
+    if (postMediaKeys.length > 0) {
+      log?.(`feishu: post message contains ${postMediaKeys.length} embedded media file(s)`);
+    }
+
+    for (const imageKey of imageKeys) {
+      try {
+        // Embedded images in post use messageResource API with image_key as file_key
+        const result = await downloadMessageResourceFeishu({
+          cfg,
+          messageId,
+          fileKey: imageKey,
+          type: "image",
+          accountId,
+        });
+
+        let contentType = result.contentType;
+        if (!contentType) {
+          contentType = await core.media.detectMime({ buffer: result.buffer });
+        }
+
+        const saved = await core.channel.media.saveMediaBuffer(
+          result.buffer,
+          contentType,
+          "inbound",
+          maxBytes,
+        );
+
+        out.push({
+          path: saved.path,
+          contentType: saved.contentType,
+          placeholder: "<media:image>",
+        });
+
+        log?.(`feishu: downloaded embedded image ${imageKey}, saved to ${saved.path}`);
+      } catch (err) {
+        log?.(`feishu: failed to download embedded image ${imageKey}: ${String(err)}`);
+      }
+    }
+
+    for (const media of postMediaKeys) {
+      try {
+        const result = await downloadMessageResourceFeishu({
+          cfg,
+          messageId,
+          fileKey: media.fileKey,
+          type: "file",
+          accountId,
+        });
+
+        let contentType = result.contentType;
+        if (!contentType) {
+          contentType = await core.media.detectMime({ buffer: result.buffer });
+        }
+
+        const saved = await core.channel.media.saveMediaBuffer(
+          result.buffer,
+          contentType,
+          "inbound",
+          maxBytes,
+        );
+
+        out.push({
+          path: saved.path,
+          contentType: saved.contentType,
+          placeholder: "<media:video>",
+        });
+
+        log?.(`feishu: downloaded embedded media ${media.fileKey}, saved to ${saved.path}`);
+      } catch (err) {
+        log?.(`feishu: failed to download embedded media ${media.fileKey}: ${String(err)}`);
+      }
+    }
+
+    return out;
+  }
+
+  // Handle other media types
+  const mediaKeys = parseMediaKeys(content, messageType);
+  if (!mediaKeys.imageKey && !mediaKeys.fileKey) {
+    return [];
+  }
+
+  try {
+    let buffer: Buffer;
+    let contentType: string | undefined;
+    let fileName: string | undefined;
+
+    // For message media, always use messageResource API
+    // The image.get API is only for images uploaded via im/v1/images, not for message attachments
+    const fileKey = mediaKeys.fileKey || mediaKeys.imageKey;
+    if (!fileKey) {
+      return [];
+    }
+
+    const resourceType = toMessageResourceType(messageType);
+    const result = await downloadMessageResourceFeishu({
+      cfg,
+      messageId,
+      fileKey,
+      type: resourceType,
+      accountId,
+    });
+    buffer = result.buffer;
+    contentType = result.contentType;
+    fileName = result.fileName || mediaKeys.fileName;
+
+    // Detect mime type if not provided
+    if (!contentType) {
+      contentType = await core.media.detectMime({ buffer });
+    }
+
+    // Save to disk using core's saveMediaBuffer
+    const saved = await core.channel.media.saveMediaBuffer(
+      buffer,
+      contentType,
+      "inbound",
+      maxBytes,
+      fileName,
+    );
+
+    out.push({
+      path: saved.path,
+      contentType: saved.contentType,
+      placeholder: inferPlaceholder(messageType),
+    });
+
+    log?.(`feishu: downloaded ${messageType} media, saved to ${saved.path}`);
+  } catch (err) {
+    log?.(`feishu: failed to download ${messageType} media: ${String(err)}`);
+  }
+
+  return out;
+}
+
 // --- Broadcast support ---
 // Resolve broadcast agent list for a given peer (group) ID.
 // Returns null if no broadcast config exists or the peer is not in the broadcast list.
@@ -180,7 +848,7 @@ export function buildFeishuAgentBody(params: {
     "content" | "senderName" | "senderOpenId" | "mentionTargets" | "messageId" | "hasAnyMention"
   >;
   quotedContent?: string;
-  permissionErrorForAgent?: FeishuPermissionError;
+  permissionErrorForAgent?: PermissionError;
   botOpenId?: string;
 }): string {
   const { ctx, quotedContent, permissionErrorForAgent, botOpenId } = params;
@@ -299,7 +967,7 @@ export async function handleFeishuMessage(params: {
 
   // Resolve sender display name (best-effort) so the agent can attribute messages correctly.
   // Optimization: skip if disabled to save API quota (Feishu free tier limit).
-  let permissionErrorForAgent: FeishuPermissionError | undefined;
+  let permissionErrorForAgent: PermissionError | undefined;
   if (feishuCfg?.resolveSenderNames ?? true) {
     const senderResult = await resolveFeishuSenderName({
       account,

extensions/feishu/src/card-action.ts

@@ -1,4 +1,4 @@
-import type { ClawdbotConfig, RuntimeEnv } from "../runtime-api.js";
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk/feishu";
 import { resolveFeishuAccount } from "./accounts.js";
 import { handleFeishuMessage, type FeishuMessageEvent } from "./bot.js";
 import { decodeFeishuCardAction, buildFeishuCardActionTextFallback } from "./card-interaction.js";

extensions/feishu/src/card-ux-launcher.ts

@@ -1,4 +1,4 @@
-import type { ClawdbotConfig, RuntimeEnv } from "../runtime-api.js";
+import type { ClawdbotConfig, RuntimeEnv } from "openclaw/plugin-sdk/feishu";
 import { createFeishuCardInteractionEnvelope } from "./card-interaction.js";
 import { FEISHU_APPROVAL_REQUEST_ACTION } from "./card-ux-approval.js";
 import { buildFeishuCardButton, buildFeishuCardInteractionContext } from "./card-ux-shared.js";

extensions/feishu/src/channel.test.ts

@@ -54,10 +54,6 @@ vi.mock("./channel.runtime.js", () => ({
 
 import { feishuPlugin } from "./channel.js";
 
-function getDescribedActions(cfg: OpenClawConfig): string[] {
-  return [...(feishuPlugin.actions?.describeMessageTool?.({ cfg })?.actions ?? [])];
-}
-
 describe("feishuPlugin.status.probeAccount", () => {
   it("uses current account credentials for multi-account config", async () => {
     const cfg = {
@@ -116,7 +112,7 @@ describe("feishuPlugin actions", () => {
   });
 
   it("advertises the expanded Feishu action surface", () => {
-    expect(getDescribedActions(cfg)).toEqual([
+    expect(feishuPlugin.actions?.listActions?.({ cfg })).toEqual([
       "send",
       "read",
       "edit",
@@ -146,7 +142,7 @@ describe("feishuPlugin actions", () => {
       },
     } as OpenClawConfig;
 
-    expect(getDescribedActions(disabledCfg)).toEqual([
+    expect(feishuPlugin.actions?.listActions?.({ cfg: disabledCfg })).toEqual([
       "send",
       "read",
       "edit",