Merge branch 'main' into fix/token-usage-input-output-breakdown

2026-03-17 10:04:47 +08:00 · 2026-03-17 10:04:47 +08:00 · 73a129378b
commit 73a129378b
parent 347976bad8 3aa4199ef0
483 changed files with 12652 additions and 4420 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@ -78,6 +78,50 @@ jobs:

          node scripts/ci-changed-scope.mjs --base "$BASE" --head HEAD

+  changed-extensions:
+    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
+    outputs:
+      has_changed_extensions: ${{ steps.changed.outputs.has_changed_extensions }}
+      changed_extensions_matrix: ${{ steps.changed.outputs.changed_extensions_matrix }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+          fetch-tags: false
+          submodules: false
+
+      - name: Ensure changed-extensions base commit
+        uses: ./.github/actions/ensure-base-commit
+        with:
+          base-sha: ${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}
+          fetch-ref: ${{ github.event_name == 'push' && github.ref_name || github.event.pull_request.base.ref }}
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          install-bun: "false"
+          install-deps: "false"
+          use-sticky-disk: "false"
+
+      - name: Detect changed extensions
+        id: changed
+        env:
+          BASE_SHA: ${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}
+        run: |
+          node --input-type=module <<'EOF'
+          import { appendFileSync } from "node:fs";
+          import { listChangedExtensionIds } from "./scripts/test-extension.mjs";
+
+          const extensionIds = listChangedExtensionIds({ base: process.env.BASE_SHA, head: "HEAD" });
+          const matrix = JSON.stringify({ include: extensionIds.map((extension) => ({ extension })) });
+
+          appendFileSync(process.env.GITHUB_OUTPUT, `has_changed_extensions=${extensionIds.length > 0}\n`, "utf8");
+          appendFileSync(process.env.GITHUB_OUTPUT, `changed_extensions_matrix=${matrix}\n`, "utf8");
+          EOF
+
  # Build dist once for Node-relevant changes and share it with downstream jobs.
  build-artifacts:
    needs: [docs-scope, changed-scope]
@ -162,6 +206,9 @@ jobs:
          - runtime: node
            task: channels
            command: pnpm test:channels
+          - runtime: node
+            task: contracts
+            command: pnpm test:contracts
          - runtime: node
            task: protocol
            command: pnpm protocol:check
@ -205,6 +252,29 @@ jobs:
        if: matrix.runtime != 'bun' || github.event_name != 'pull_request'
        run: ${{ matrix.command }}

+  extension-fast:
+    name: "extension-fast (${{ matrix.extension }})"
+    needs: [docs-scope, changed-scope, changed-extensions]
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true' && needs.changed-extensions.outputs.has_changed_extensions == 'true'
+    runs-on: blacksmith-16vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.changed-extensions.outputs.changed_extensions_matrix) }}
+    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 changed extension tests
+        run: pnpm test:extension ${{ matrix.extension }}
+
  # Types, lint, and format check.
  check:
    name: "check"
@ -252,6 +322,12 @@ jobs:
      - name: Build dist
        run: pnpm build

+      - name: Smoke test CLI launcher help
+        run: node openclaw.mjs --help
+
+      - name: Smoke test CLI launcher status json
+        run: node openclaw.mjs status --json --timeout 1
+
      - name: Check CLI startup memory
        run: pnpm test:startup:memory

@ -385,11 +461,20 @@ jobs:
        run: |
          set -euo pipefail

-          if [ "${{ github.event_name }}" = "push" ]; then
-            BASE="${{ github.event.before }}"
-          else
-            BASE="${{ github.event.pull_request.base.sha }}"
-          fi
+          BASE="$(
+            python - <<'PY'
+            import json
+            import os
+
+            with open(os.environ["GITHUB_EVENT_PATH"], "r", encoding="utf-8") as fh:
+                event = json.load(fh)
+
+            if os.environ["GITHUB_EVENT_NAME"] == "push":
+                print(event["before"])
+            else:
+                print(event["pull_request"]["base"]["sha"])
+            PY
+          )"

          mapfile -t workflow_files < <(git diff --name-only "$BASE" HEAD -- '.github/workflows/*.yml' '.github/workflows/*.yaml')
          if [ "${#workflow_files[@]}" -eq 0 ]; then
--- a/.gitignore
+++ b/.gitignore
@ -4,6 +4,7 @@ node_modules
 docker-compose.override.yml
 docker-compose.extra.yml
 dist
+dist-runtime
 pnpm-lock.yaml
 bun.lock
 bun.lockb
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -13,49 +13,53 @@ Docs: https://docs.openclaw.ai
 - Plugins/bundles: add compatible Codex, Claude, and Cursor bundle discovery/install support, map bundle skills into OpenClaw skills, and apply Claude bundle `settings.json` defaults to embedded Pi with shell overrides sanitized.
 - Plugins/providers: move OpenRouter, GitHub Copilot, and OpenAI Codex provider/runtime logic into bundled plugins, including dynamic model fallback, runtime auth exchange, stream wrappers, capability hints, and cache-TTL policy.
 - Plugins/agent integrations: broaden the plugin surface for app-server integrations with channel-aware commands, interactive callbacks, inbound claims, and Discord/Telegram conversation binding support. (#45318) Thanks @huntharo and @vincentkoc.
- Install/update: allow package-manager installs from GitHub `main` via `openclaw update --tag main`, installer `--version main`, or direct npm/pnpm git specs.
+- Install/update: allow package-manager installs from GitHub `main` via `openclaw update --tag main`, installer `--version main`, or direct npm/pnpm git specs. (#47630) Thanks @vincentkoc.
 - Gateway/health monitor: add configurable stale-event thresholds and restart limits, plus per-channel and per-account `healthMonitor.enabled` overrides, while keeping the existing global disable path on `gateway.channelHealthCheckMinutes=0`. (#42107) Thanks @rstar327.
 - Android/mobile: add a system-aware dark theme across onboarding and post-onboarding screens so the app follows the device theme through setup, chat, and voice flows. (#46249) Thanks @sibbl.
- Feishu/ACP: add current-conversation ACP and subagent session binding for supported DMs and topic conversations, including completion delivery back to the originating Feishu conversation. (#46819)
- Plugins/marketplaces: add Claude marketplace registry resolution, `plugin@marketplace` installs, marketplace listing, and update support, plus Docker E2E coverage for local and official marketplace flows. Thanks @vincentkoc.
- Feishu/cards: add structured interactive approval and quick-action launcher cards, preserve callback user and conversation context through routing, and keep legacy card-action fallback behavior so common actions can run without typing raw commands. (#47873)
- Feishu/streaming: add `onReasoningStream` and `onReasoningEnd` support to streaming cards, so `/reasoning stream` renders thinking tokens as markdown blockquotes in the same card — matching the Telegram channel's reasoning lane behavior. (#46029)
+- Feishu/ACP: add current-conversation ACP and subagent session binding for supported DMs and topic conversations, including completion delivery back to the originating Feishu conversation. (#46819) Thanks @Takhoffman.
+- Plugins/marketplaces: add Claude marketplace registry resolution, `plugin@marketplace` installs, marketplace listing, and update support, plus Docker E2E coverage for local and official marketplace flows. (#48058) Thanks @vincentkoc.
+- Feishu/cards: add structured interactive approval and quick-action launcher cards, preserve callback user and conversation context through routing, and keep legacy card-action fallback behavior so common actions can run without typing raw commands. (#47873) Thanks @Takhoffman.
+- Feishu/streaming: add `onReasoningStream` and `onReasoningEnd` support to streaming cards, so `/reasoning stream` renders thinking tokens as markdown blockquotes in the same card — matching the Telegram channel's reasoning lane behavior. (#46029) Thanks @day253.
 - Feishu/cards: add identity-aware structured card headers and note footers for Feishu replies and direct sends, while keeping that presentation wired through the shared outbound identity path. (#29938) Thanks @nszhsl.
 - Android/nodes: add `callLog.search` plus shared Call Log permission wiring so Android nodes can search recent call history through the gateway. (#44073) Thanks @lxk7280.
 - Plugins/MiniMax: merge the bundled MiniMax API and MiniMax OAuth plugin surfaces into a single default-on `minimax` plugin, while keeping legacy `minimax-portal-auth` config ids aliased for compatibility.
 - Telegram/actions: add `topic-edit` for forum-topic renames and icon updates while sharing the same Telegram topic-edit transport used by the plugin runtime. (#47798) Thanks @obviyus.
- Refactor/channels: remove the legacy channel shim directories and point channel-specific imports directly at the extension-owned implementations. (#45967) thanks @scoootscooob.
+- Telegram/error replies: add a default-off `channels.telegram.silentErrorReplies` setting so bot error replies can be delivered silently across regular replies, native commands, and fallback sends. (#19776) Thanks @ImLukeF.
+- Refactor/channels: remove the legacy channel shim directories and point channel-specific imports directly at the extension-owned implementations. (#45967) Thanks @scoootscooob.
 - Docs/Zalo: clarify the Marketplace-bot support matrix and config guidance so the Zalo channel docs match current Bot Creator behavior more closely. (#47552) Thanks @No898.
 - secrets: harden read-only SecretRef command paths and diagnostics. (#47794) Thanks @joshavant.
+- Browser/existing-session: support `browser.profiles.<name>.userDataDir` so Chrome DevTools MCP can attach to Brave, Edge, and other Chromium-based browsers through their own user data directories. (#48170) Thanks @velvet-shark.
+- Skills/prompt budget: preserve all registered skills via a compact catalog fallback before dropping entries when the full prompt format exceeds `maxSkillsPromptChars`. (#47553) Thanks @snese.

 ### 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. Thanks @vincentkoc.
+- 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.

 ### Fixes

 - Google auth/Node 25: patch `gaxios` to use native fetch without injecting `globalThis.window`, while translating proxy and mTLS transport settings so Google Vertex and Google Chat auth keep working on Node 25. (#47914) Thanks @pdd-cli.
- Gateway/startup: load bundled channel plugins from compiled `dist/extensions` entries in built installs, so gateway boot no longer recompiles bundled extension TypeScript on every startup and WhatsApp-class cold starts drop back to seconds instead of tens of seconds or worse.
+- Gateway/startup: load bundled channel plugins from compiled `dist/extensions` entries in built installs, so gateway boot no longer recompiles bundled extension TypeScript on every startup and WhatsApp-class cold starts drop back to seconds instead of tens of seconds or worse. (#47560) Thanks @ngutman.
 - Plugins/context engines: enforce owner-aware context-engine registration on both loader and public SDK paths so plugins cannot spoof privileged ownership, claim the core `legacy` engine id, or overwrite an existing engine id through direct SDK imports. (#47595) Thanks @vincentkoc.
 - Browser/remote CDP: honor strict browser SSRF policy during remote CDP reachability and `/json/version` discovery checks, redact sensitive `cdpUrl` tokens from status output, and warn when remote CDP targets private/internal hosts.
- Gateway/plugins: pin runtime webhook routes to the gateway startup registry so channel webhooks keep working across plugin-registry churn, and make plugin auth + dispatch resolve routes from the same live HTTP-route registry. Fixes #46924 and #47041.
- Gateway/auth: ignore spoofed loopback hops in trusted forwarding chains and block device approvals that request scopes above the caller session. Thanks @vincentkoc.
+- Gateway/plugins: pin runtime webhook routes to the gateway startup registry so channel webhooks keep working across plugin-registry churn, and make plugin auth + dispatch resolve routes from the same live HTTP-route registry. (#47902) Fixes #46924 and #47041. Thanks @steipete.
+- Gateway/auth: ignore spoofed loopback hops in trusted forwarding chains and block device approvals that request scopes above the caller session. (#46800) Thanks @vincentkoc.
 - Gateway/restart: defer externally signaled unmanaged restarts through the in-process idle drain, and preserve the restored subagent run as remap fallback during orphan recovery so resumed sessions do not duplicate work. (#47719) Thanks @joeykrug.
 - Control UI/session routing: preserve established external delivery routes when webchat views or sends in externally originated sessions, so subagent completions still return to the original channel instead of the dashboard. (#47797) Thanks @brokemac79.
- Configure/startup: move outbound send-deps resolution into a lightweight helper so `openclaw configure` no longer stalls after the banner while eagerly loading channel plugins. (#46301) thanks @scoootscooob.
+- Configure/startup: move outbound send-deps resolution into a lightweight helper so `openclaw configure` no longer stalls after the banner while eagerly loading channel plugins. (#46301) Thanks @scoootscooob.
 - CLI/startup: lazy-load channel add and root help startup paths to trim avoidable RSS and help latency on constrained hosts. (#46784) Thanks @vincentkoc.
 - CLI/onboarding: import static provider definitions directly for onboarding model/config helpers so those paths no longer pull provider discovery just for built-in defaults. (#47467) Thanks @vincentkoc.
 - CLI/auth choice: lazy-load plugin/provider fallback resolution so mapped auth choices stay on the static path and only unknown choices pay the heavy provider load. (#47495) Thanks @vincentkoc.
 - CLI: avoid loading provider discovery during startup model normalization. (#46522) Thanks @ItsAditya-xyz and @vincentkoc.
 - Security/device pairing: harden `device.token.rotate` deny handling by keeping public failures generic while logging internal deny reasons and preserving approved-baseline enforcement. (`GHSA-7jrw-x62h-64p8`)
 - Inbound policy hardening: tighten callback and webhook sender checks across Mattermost and Google Chat, match Nextcloud Talk rooms by stable room token, and treat explicit empty Twitch allowlists as deny-all. (#46787) Thanks @zpbrent, @ijxpwastaken and @vincentkoc.
- Webhooks/runtime: move auth earlier and tighten pre-auth body limits and timeouts across bundled webhook handlers, including slow-body handling for Mattermost slash commands. Thanks @vincentkoc.
- Email/webhook wrapping: sanitize sender and subject metadata before external-content wrapping so metadata fields cannot break the wrapper structure. Thanks @vincentkoc.
- Tools/apply-patch: revalidate workspace-only delete and directory targets immediately before mutating host paths. Thanks @vincentkoc.
- Gateway/config views: strip embedded credentials from URL-based endpoint fields before returning read-only account and config snapshots. Thanks @vincentkoc.
+- Webhooks/runtime: move auth earlier and tighten pre-auth body limits and timeouts across bundled webhook handlers, including slow-body handling for Mattermost slash commands. (#46802) Thanks @vincentkoc.
+- Email/webhook wrapping: sanitize sender and subject metadata before external-content wrapping so metadata fields cannot break the wrapper structure. (#46816) Thanks @vincentkoc.
+- Tools/apply-patch: revalidate workspace-only delete and directory targets immediately before mutating host paths. (#46803) Thanks @vincentkoc.
+- Gateway/config views: strip embedded credentials from URL-based endpoint fields before returning read-only account and config snapshots. (#46799) Thanks @vincentkoc.
 - ACP/approvals: use canonical tool identity for prompting decisions and fail closed when conflicting tool identity hints are present. (#46817) Thanks @zpbrent and @vincentkoc.
 - ACP: require admin scope for mutating internal actions. (#46789) Thanks @tdjackey and @vincentkoc.
- Subagents/follow-ups: require the same controller ownership checks for `/subagents send` as other control actions, so leaf sessions cannot message nested child runs they do not control. Thanks @vincentkoc.
+- Subagents/follow-ups: require the same controller ownership checks for `/subagents send` as other control actions, so leaf sessions cannot message nested child runs they do not control. (#46801) Thanks @vincentkoc.
 - macOS/canvas actions: keep unattended local agent actions on trusted in-app canvas surfaces only, and stop exposing the deep-link fallback key to arbitrary page scripts. (#46790) Thanks @vincentkoc.
 - Agents/compaction: extend the enclosing run deadline once while compaction is actively in flight, and abort the underlying SDK compaction on timeout/cancel so large-session compactions stop freezing mid-run. (#46889) Thanks @asyncjason.
 - Agents/openai-compatible tool calls: deduplicate repeated tool call ids across live assistant messages and replayed history so OpenAI-compatible backends no longer reject duplicate `tool_call_id` values with HTTP 400. (#40996) Thanks @xaeon2026.
@ -63,35 +67,46 @@ Docs: https://docs.openclaw.ai
 - Models/OpenRouter runtime capabilities: fetch uncatalogued OpenRouter model metadata on first use so newly added vision models keep image input instead of silently degrading to text-only, with top-level capability field fallbacks for `/api/v1/models`. (#45824) Thanks @DJjjjhao.
 - Channels/plugins: keep shared interactive payloads merge-ready by fixing Slack custom callback routing and repeat-click dedupe, allowing interactive-only sends, and preserving ordered Discord shared text blocks. (#47715) Thanks @vincentkoc.
 - Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
- Slack/interactive replies: preserve `channelData.slack.blocks` through live DM delivery and preview-finalized edits so Block Kit button and select directives render instead of falling back to raw text. (#45890) Thanks @vincentkoc.
- Feishu/actions: expand the runtime action surface with message read/edit, explicit thread replies, pinning, and operator-facing chat/member inspection so Feishu can operate more of the workspace directly.
+- Feishu/actions: expand the runtime action surface with message read/edit, explicit thread replies, pinning, and operator-facing chat/member inspection so Feishu can operate more of the workspace directly. (#47968) Thanks @Takhoffman.
 - Feishu/topic threads: fetch full thread context, including prior bot replies, when starting a topic-thread session so follow-up turns in Feishu topics keep the right conversation state. (#45254) Thanks @Coobiw.
- Feishu/media: keep native image, file, audio, and video/media handling aligned across outbound sends, inbound downloads, thread replies, directory/action aliases, and capability docs so unsupported areas are explicit instead of implied.
- WhatsApp/reconnect: restore the append recency filter in the extension inbox monitor and handle protobuf `Long` timestamps correctly, so fresh post-reconnect append messages are processed while stale history sync stays suppressed. (#42588) thanks @MonkeyLeeT.
+- Feishu/media: keep native image, file, audio, and video/media handling aligned across outbound sends, inbound downloads, thread replies, directory/action aliases, and capability docs so unsupported areas are explicit instead of implied. (#47968) Thanks @Takhoffman.
+- WhatsApp/reconnect: restore the append recency filter in the extension inbox monitor and handle protobuf `Long` timestamps correctly, so fresh post-reconnect append messages are processed while stale history sync stays suppressed. (#42588) Thanks @MonkeyLeeT.
 - WhatsApp/login: wait for pending creds writes before reopening after Baileys `515` pairing restarts in both QR login and `channels login` flows, and keep the restart coverage pinned to the real wrapped error shape plus per-account creds queues. (#27910) Thanks @asyncjason.
 - Telegram/message send: forward `--force-document` through the `sendPayload` path as well as `sendMedia`, so Telegram payload sends with `channelData` keep uploading images as documents instead of silently falling back to compressed photo sends. (#47119) Thanks @thepagent.
- Telegram/message chunking: preserve spaces, paragraph separators, and word boundaries when HTML overflow rechunking splits formatted replies. (#47274)
- Z.AI/onboarding: detect a working default model even for explicit `zai-coding-*` endpoint choices, so Coding Plan setup can keep the selected endpoint while defaulting to `glm-5` when available or `glm-4.7` as fallback. (#45969)
+- Telegram/message chunking: preserve spaces, paragraph separators, and word boundaries when HTML overflow rechunking splits formatted replies. (#47274) Thanks @obviyus.
+- Z.AI/onboarding: detect a working default model even for explicit `zai-coding-*` endpoint choices, so Coding Plan setup can keep the selected endpoint while defaulting to `glm-5` when available or `glm-4.7` as fallback. (#45969) Thanks @obviyus.
 - Z.AI/onboarding: add `glm-5-turbo` to the default Z.AI provider catalog so onboarding-generated configs expose the new model alongside the existing GLM defaults. (#46670) Thanks @tomsun28.
- Zalo Personal/group gating: stop reapplying `dmPolicy.allowFrom` as a sender gate for already-allowlisted groups when `groupAllowFrom` is unset, so any member of an allowed group can trigger replies while DMs stay restricted. (#40146)
+- Zalo Personal/group gating: stop reapplying `dmPolicy.allowFrom` as a sender gate for already-allowlisted groups when `groupAllowFrom` is unset, so any member of an allowed group can trigger replies while DMs stay restricted. (#46663) Fixes #40146. Thanks @Takhoffman.
 - Zalo/plugin runtime: export `resolveClientIp` from `openclaw/plugin-sdk/zalo` so installed builds no longer crash on startup when the webhook monitor loads from the packaged extension instead of the monorepo source tree. (#46549) Thanks @No898.
- Plugins/install precedence: keep bundled plugins ahead of auto-discovered globals by default, but let an explicitly installed plugin record win its own duplicate-id tie so installed channel plugins load from `~/.openclaw/extensions` after `openclaw plugins install`.
- Plugins/scoped ids: preserve scoped plugin ids during install and config keying, and keep bundled plugins ahead of discovered duplicate ids by default so `@scope/name` plugins no longer collide with unscoped installs. Thanks @vincentkoc.
- Gateway/watch mode: restart on bundled-plugin package and manifest metadata changes, rebuild `dist` for extension source and `tsdown.config.ts` changes, and still ignore extension docs. (#47571) thanks @gumadeiras.
+- Plugins/install precedence: keep bundled plugins ahead of auto-discovered globals by default, but let an explicitly installed plugin record win its own duplicate-id tie so installed channel plugins load from `~/.openclaw/extensions` after `openclaw plugins install`. (#46722) Thanks @Takhoffman.
+- Control UI/logging: make browser-safe logger imports avoid eager temp-dir resolution so the bundled Control UI no longer crashes to a blank screen when logging reaches `tmp-openclaw-dir`. (#48469) Fixes #48062. Thanks @7inspire.
+- Plugins/scoped ids: preserve scoped plugin ids during install and config keying, and keep bundled plugins ahead of discovered duplicate ids by default so `@scope/name` plugins no longer collide with unscoped installs. (#47413) Thanks @vincentkoc.
+- Gateway/watch mode: restart on bundled-plugin package and manifest metadata changes, rebuild `dist` for extension source and `tsdown.config.ts` changes, and still ignore extension docs. (#47571) Thanks @gumadeiras.
 - Gateway/watch mode: recreate bundled plugin runtime metadata after clean or stale `dist` states, so `pnpm gateway:watch` no longer fails on missing `dist/extensions/*/openclaw.plugin.json` manifests after a rebuild. Thanks @gumadeiras.
- Control UI/chat sessions: show human-readable labels in the grouped session dropdown again, keep unique scoped fallbacks when metadata is missing, and disambiguate duplicate labels only when needed. (#45130) thanks @luzhidong.
+- Control UI/chat sessions: show human-readable labels in the grouped session dropdown again, keep unique scoped fallbacks when metadata is missing, and disambiguate duplicate labels only when needed. (#45130) Thanks @luzhidong.
 - Control UI: scope persisted session selection per gateway, prevent stale session bleed across tokenized gateway opens, and cap stored gateway session history. (#47453) Thanks @sallyom.
- Control UI/dashboard: preserve structured gateway shutdown reasons across restart disconnects so config-triggered restarts no longer fall back to `disconnected (1006): no reason`. (#46532) Thanks @vincentkoc.
+- Control UI/dashboard: preserve structured gateway shutdown reasons across restart disconnects so config-triggered restarts no longer fall back to `disconnected (1006): no reason`. (#46580) Fixes #46532. Thanks @vincentkoc.
 - Android/chat: theme the thinking dropdown and TLS trust dialogs explicitly so popup surfaces match the active app theme instead of falling back to mismatched Material defaults.
 - Group mention gating: reject invalid and unsafe nested-repetition `mentionPatterns`, reuse the shared safe config-regex compiler across mention stripping and detection, and cache strip-time regex compilation so noisy groups avoid repeated recompiles.
- Browser/profiles: drop the auto-created `chrome-relay` browser profile; users who need the Chrome extension relay must now create their own profile via `openclaw browser create-profile`. (#45777) Thanks @odysseus0.
+- Browser/profiles: drop the auto-created `chrome-relay` browser profile; users who need the Chrome extension relay must now create their own profile via `openclaw browser create-profile`. (#46596) Fixes #45777. Thanks @odysseus0.
 - CI/channel test routing: move the built-in channel suites into `test:channels` and keep them out of `test:extensions`, so extension CI no longer fails after the channel migration while targeted test routing still sends Slack, Signal, and iMessage suites to the right lane. (#46066) Thanks @scoootscooob.
 - Docs/Mintlify: fix MDX marker syntax on Perplexity, Model Providers, Moonshot, and exec approvals pages so local docs preview no longer breaks rendering or leaves stale pages unpublished. (#46695) Thanks @velvet-shark.
 - Gateway/config validation: stop treating the implicit default memory slot as a required explicit plugin config, so startup no longer fails with `plugins.slots.memory: plugin not found: memory-core` when `memory-core` was only inferred. (#47494) Thanks @ngutman.
 - Tlon: honor explicit empty allowlists and defer cite expansion. (#46788) Thanks @zpbrent and @vincentkoc.
 - Nodes/pending actions: re-check queued foreground actions against the current node command policy before returning them to the node. (#46815) Thanks @zpbrent and @vincentkoc.
- Node/startup: remove leftover debug `console.log("node host PATH: ...")` that printed the resolved PATH on every `openclaw node run` invocation. (#46411)
+- Node/startup: remove leftover debug `console.log("node host PATH: ...")` that printed the resolved PATH on every `openclaw node run` invocation. (#46515) Fixes #46411. Thanks @ademczuk.
 - CLI/completion: reduce recursive completion-script string churn and fix nested PowerShell command-path matching so generated nested completions resolve on PowerShell too. (#45537) Thanks @yiShanXin and @vincentkoc.
+- Slack/startup: harden `@slack/bolt` import interop across current bundled runtime shapes so Slack monitors no longer crash with `App is not a constructor` after plugin-sdk bundling changes. (#45953) Thanks @merc1305.
+- Windows/gateway status: accept `schtasks` `Last Result` output as an alias for `Last Run Result`, so running scheduled-task installs no longer show `Runtime: unknown`. (#47844) Thanks @MoerAI.
+- ACP/acpx: resolve the bundled plugin root from the actual plugin directory so plugin-local installs stay under `dist/extensions/acpx` instead of escaping to `dist/extensions` and failing runtime setup. (#47601) Thanks @ngutman.
+- Gateway/websocket pairing bypass for disabled auth: skip device-pairing enforcement for Control UI operator sessions when `gateway.auth.mode=none`, so reverse-proxied dashboards no longer get stuck on `pairing required` despite auth being explicitly disabled. (#47148) Thanks @ademczuk.
+- Control UI/model switching: preserve the selected provider prefix when switching models from the chat dropdown, so multi-provider setups no longer send `anthropic/gpt-5.2`-style mismatches when the user picked `openai/gpt-5.2`. (#47581) Thanks @chrishham.
+- Control UI/storage: scope persisted settings keys by gateway base path, with migration from the legacy shared key, so multiple gateways under one domain stop overwriting each other's dashboard preferences. (#47932) Thanks @bobBot-claw.
+- Agents/usage tracking: stop forcing `supportsUsageInStreaming: false` on non-native OpenAI-completions providers so compatible backends report token usage and cost again instead of showing all zeros. (#46500) Fixes #46142. Thanks @ademczuk.
+- Plugins/subagents: preserve gateway-owned plugin subagent access across runtime, tool, and embedded-runner load paths so gateway plugin tools and context engines can still spawn and manage subagents after the loader cache split. (#46648) Thanks @jalehman.
+- Control UI/overview: keep the language dropdown aligned with the persisted locale during dashboard startup so refreshing the page does not fall back to English before locale hydration completes. (#48019) Thanks @git-jxj.
+- Agents/compaction: rerun transcript repair after `session.compact()` so orphaned `tool_result` blocks cannot survive compaction and break later Anthropic requests. (#16095) thanks @claw-sylphx.
+- Agents/compaction: trigger overflow recovery from the tool-result guard once post-compaction context still exceeds the safe threshold, so long tool loops compact before the next model call hard-fails. (#29371) thanks @keshav55.

 ## 2026.3.13

@ -261,6 +276,10 @@ Docs: https://docs.openclaw.ai
 - Agents/Anthropic replay: drop replayed assistant thinking blocks for native Anthropic and Bedrock Claude providers so persisted follow-up turns no longer fail on stored thinking blocks. (#44843) Thanks @jmcte.
 - Docs/Brave pricing: escape literal dollar signs in Brave Search cost text so the docs render the free credit and per-request pricing correctly. (#44989) Thanks @keelanfh.
 - Feishu/file uploads: preserve literal UTF-8 filenames in `im.file.create` so Chinese and other non-ASCII filenames no longer appear percent-encoded in chat. (#34262) Thanks @fabiaodemianyang and @KangShuaiFu.
+- Agents/compaction safeguard: trim large kept `toolResult` payloads consistently for budgeting, pruning, and identifier seeding, then restore preserved payloads after prune so oversized safeguard summaries stay stable. (#44133) thanks @SayrWolfridge.
+- Agents/compaction: compare post-compaction token sanity checks against full-session pre-compaction totals and skip the check when token estimation fails, so sessions with large bootstrap context keep real token counts instead of falling back to unknown. (#28347) thanks @efe-arv.
+- Discord/gateway startup: treat plain-text and transient `/gateway/bot` metadata fetch failures as transient startup errors so Discord gateway boot no longer crashes on unhandled rejections. (#44397) Thanks @jalehman.
+- Agents/Ollama overflow: rewrite Ollama `prompt too long` API payloads through the normal context-overflow sanitizer so embedded sessions keep the friendly overflow copy and auto-compaction trigger. (#34019) thanks @lishuaigit.

 ## 2026.3.11

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -89,6 +89,11 @@ Welcome to the lobster tank! 🦞

 - Test locally with your OpenClaw instance
 - Run tests: `pnpm build && pnpm check && pnpm test`
+- For extension/plugin changes, run the fast local lane first:
+  - `pnpm test:extension <extension-name>`
+  - `pnpm test:extension --list` to see valid extension ids
+  - If you changed shared plugin or channel surfaces, run `pnpm test:contracts`
+  - If you changed broader runtime behavior, still run the relevant wider lanes (`pnpm test:extensions`, `pnpm test:channels`, or `pnpm test`) before asking for review
 - If you have access to Codex, run `codex review --base origin/main` locally before opening or updating your PR. Treat this as the current highest standard of AI review, even if GitHub Codex review also runs.
 - Ensure CI checks pass
 - Keep PRs focused (one thing per PR; do not mix unrelated concerns)
--- a/README.md
+++ b/README.md
@ -23,10 +23,10 @@ It answers you on the channels you already use (WhatsApp, Telegram, Slack, Disco

 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

-[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [Vision](VISION.md) · [DeepWiki](https://deepwiki.com/openclaw/openclaw) · [Getting Started](https://docs.openclaw.ai/start/getting-started) · [Updating](https://docs.openclaw.ai/install/updating) · [Showcase](https://docs.openclaw.ai/start/showcase) · [FAQ](https://docs.openclaw.ai/help/faq) · [Wizard](https://docs.openclaw.ai/start/wizard) · [Nix](https://github.com/openclaw/nix-openclaw) · [Docker](https://docs.openclaw.ai/install/docker) · [Discord](https://discord.gg/clawd)
+[Website](https://openclaw.ai) · [Docs](https://docs.openclaw.ai) · [Vision](VISION.md) · [DeepWiki](https://deepwiki.com/openclaw/openclaw) · [Getting Started](https://docs.openclaw.ai/start/getting-started) · [Updating](https://docs.openclaw.ai/install/updating) · [Showcase](https://docs.openclaw.ai/start/showcase) · [FAQ](https://docs.openclaw.ai/help/faq) · [Onboarding](https://docs.openclaw.ai/start/wizard) · [Nix](https://github.com/openclaw/nix-openclaw) · [Docker](https://docs.openclaw.ai/install/docker) · [Discord](https://discord.gg/clawd)

-Preferred setup: run the onboarding wizard (`openclaw onboard`) in your terminal.
-The wizard guides you step by step through setting up the gateway, workspace, channels, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
+Preferred setup: run `openclaw onboard` in your terminal.
+OpenClaw Onboard guides you step by step through setting up the gateway, workspace, channels, and skills. It is the recommended CLI setup path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
 New install? Start here: [Getting started](https://docs.openclaw.ai/start/getting-started)

@ -58,7 +58,7 @@ npm install -g openclaw@latest
 openclaw onboard --install-daemon
 ```

-The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
+OpenClaw Onboard installs the Gateway daemon (launchd/systemd user service) so it stays running.

 ## Quick start (TL;DR)

@ -132,7 +132,7 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies.
 - **[Live Canvas](https://docs.openclaw.ai/platforms/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.openclaw.ai/platforms/mac/canvas#canvas-a2ui).
 - **[First-class tools](https://docs.openclaw.ai/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
 - **[Companion apps](https://docs.openclaw.ai/platforms/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.openclaw.ai/nodes).
- **[Onboarding](https://docs.openclaw.ai/start/wizard) + [skills](https://docs.openclaw.ai/tools/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+- **[Onboarding](https://docs.openclaw.ai/start/wizard) + [skills](https://docs.openclaw.ai/tools/skills)** — onboarding-driven setup with bundled/managed/workspace skills.

 ## Star History

@ -143,7 +143,7 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies.
 ### Core platform

 - [Gateway WS control plane](https://docs.openclaw.ai/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.openclaw.ai/web), and [Canvas host](https://docs.openclaw.ai/platforms/mac/canvas#canvas-a2ui).
- [CLI surface](https://docs.openclaw.ai/tools/agent-send): gateway, agent, send, [wizard](https://docs.openclaw.ai/start/wizard), and [doctor](https://docs.openclaw.ai/gateway/doctor).
+- [CLI surface](https://docs.openclaw.ai/tools/agent-send): gateway, agent, send, [onboarding](https://docs.openclaw.ai/start/wizard), and [doctor](https://docs.openclaw.ai/gateway/doctor).
 - [Pi agent runtime](https://docs.openclaw.ai/concepts/agent) in RPC mode with tool streaming and block streaming.
 - [Session model](https://docs.openclaw.ai/concepts/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.openclaw.ai/channels/groups).
 - [Media pipeline](https://docs.openclaw.ai/nodes/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.openclaw.ai/nodes/audio).
@ -422,7 +422,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [Run the Gateway by the book with the operational runbook.](https://docs.openclaw.ai/gateway)
 - [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://docs.openclaw.ai/web)
 - [Understand remote access over SSH tunnels or tailnets.](https://docs.openclaw.ai/gateway/remote)
- [Follow the onboarding wizard flow for a guided setup.](https://docs.openclaw.ai/start/wizard)
+- [Follow OpenClaw Onboard for a guided setup.](https://docs.openclaw.ai/start/wizard)
 - [Wire external triggers via the webhook surface.](https://docs.openclaw.ai/automation/webhook)
 - [Set up Gmail Pub/Sub triggers.](https://docs.openclaw.ai/automation/gmail-pubsub)
 - [Learn the macOS menu bar companion details.](https://docs.openclaw.ai/platforms/mac/menu-bar)
--- a/apps/android/app/src/main/java/ai/openclaw/app/MainActivity.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/MainActivity.kt
@ -18,14 +18,13 @@ import kotlinx.coroutines.launch
 class MainActivity : ComponentActivity() {
  private val viewModel: MainViewModel by viewModels()
  private lateinit var permissionRequester: PermissionRequester
+  private var didAttachRuntimeUi = false
+  private var didStartNodeService = false

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    WindowCompat.setDecorFitsSystemWindows(window, false)
    permissionRequester = PermissionRequester(this)
-    viewModel.camera.attachLifecycleOwner(this)
-    viewModel.camera.attachPermissionRequester(permissionRequester)
-    viewModel.sms.attachPermissionRequester(permissionRequester)

    lifecycleScope.launch {
      repeatOnLifecycle(Lifecycle.State.STARTED) {
@ -39,6 +38,20 @@ class MainActivity : ComponentActivity() {
      }
    }

+    lifecycleScope.launch {
+      repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.runtimeInitialized.collect { ready ->
+          if (!ready || didAttachRuntimeUi) return@collect
+          viewModel.attachRuntimeUi(owner = this@MainActivity, permissionRequester = permissionRequester)
+          didAttachRuntimeUi = true
+          if (!didStartNodeService) {
+            NodeForegroundService.start(this@MainActivity)
+            didStartNodeService = true
+          }
+        }
+      }
+    }
+
    setContent {
      OpenClawTheme {
        Surface(modifier = Modifier) {
@ -46,9 +59,6 @@ class MainActivity : ComponentActivity() {
        }
      }
    }
-
-    // Keep startup path lean: start foreground service after first frame.
-    window.decorView.post { NodeForegroundService.start(this) }
  }

  override fun onStart() {
--- a/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/MainViewModel.kt
@ -2,209 +2,268 @@ package ai.openclaw.app

 import android.app.Application
 import androidx.lifecycle.AndroidViewModel
-import ai.openclaw.app.gateway.GatewayEndpoint
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.viewModelScope
+import ai.openclaw.app.chat.ChatMessage
+import ai.openclaw.app.chat.ChatPendingToolCall
+import ai.openclaw.app.chat.ChatSessionEntry
 import ai.openclaw.app.chat.OutgoingAttachment
+import ai.openclaw.app.gateway.GatewayEndpoint
 import ai.openclaw.app.node.CameraCaptureManager
 import ai.openclaw.app.node.CanvasController
 import ai.openclaw.app.node.SmsManager
 import ai.openclaw.app.voice.VoiceConversationEntry
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.flatMapLatest
+import kotlinx.coroutines.flow.flowOf
+import kotlinx.coroutines.flow.stateIn

+@OptIn(ExperimentalCoroutinesApi::class)
 class MainViewModel(app: Application) : AndroidViewModel(app) {
-  private val runtime: NodeRuntime = (app as NodeApp).runtime
+  private val nodeApp = app as NodeApp
+  private val prefs = nodeApp.prefs
+  private val runtimeRef = MutableStateFlow<NodeRuntime?>(null)
+  private var foreground = true

-  val canvas: CanvasController = runtime.canvas
-  val canvasCurrentUrl: StateFlow<String?> = runtime.canvas.currentUrl
-  val canvasA2uiHydrated: StateFlow<Boolean> = runtime.canvasA2uiHydrated
-  val canvasRehydratePending: StateFlow<Boolean> = runtime.canvasRehydratePending
-  val canvasRehydrateErrorText: StateFlow<String?> = runtime.canvasRehydrateErrorText
-  val camera: CameraCaptureManager = runtime.camera
-  val sms: SmsManager = runtime.sms
+  private fun ensureRuntime(): NodeRuntime {
+    runtimeRef.value?.let { return it }
+    val runtime = nodeApp.ensureRuntime()
+    runtime.setForeground(foreground)
+    runtimeRef.value = runtime
+    return runtime
+  }

-  val gateways: StateFlow<List<GatewayEndpoint>> = runtime.gateways
-  val discoveryStatusText: StateFlow<String> = runtime.discoveryStatusText
+  private fun <T> runtimeState(
+    initial: T,
+    selector: (NodeRuntime) -> StateFlow<T>,
+  ): StateFlow<T> =
+    runtimeRef
+      .flatMapLatest { runtime -> runtime?.let(selector) ?: flowOf(initial) }
+      .stateIn(viewModelScope, SharingStarted.Eagerly, initial)

-  val isConnected: StateFlow<Boolean> = runtime.isConnected
-  val isNodeConnected: StateFlow<Boolean> = runtime.nodeConnected
-  val statusText: StateFlow<String> = runtime.statusText
-  val serverName: StateFlow<String?> = runtime.serverName
-  val remoteAddress: StateFlow<String?> = runtime.remoteAddress
-  val pendingGatewayTrust: StateFlow<NodeRuntime.GatewayTrustPrompt?> = runtime.pendingGatewayTrust
-  val isForeground: StateFlow<Boolean> = runtime.isForeground
-  val seamColorArgb: StateFlow<Long> = runtime.seamColorArgb
-  val mainSessionKey: StateFlow<String> = runtime.mainSessionKey
+  val runtimeInitialized: StateFlow<Boolean> =
+    runtimeRef
+      .flatMapLatest { runtime -> flowOf(runtime != null) }
+      .stateIn(viewModelScope, SharingStarted.Eagerly, false)

-  val cameraHud: StateFlow<CameraHudState?> = runtime.cameraHud
-  val cameraFlashToken: StateFlow<Long> = runtime.cameraFlashToken
+  val canvasCurrentUrl: StateFlow<String?> = runtimeState(initial = null) { it.canvas.currentUrl }
+  val canvasA2uiHydrated: StateFlow<Boolean> = runtimeState(initial = false) { it.canvasA2uiHydrated }
+  val canvasRehydratePending: StateFlow<Boolean> = runtimeState(initial = false) { it.canvasRehydratePending }
+  val canvasRehydrateErrorText: StateFlow<String?> = runtimeState(initial = null) { it.canvasRehydrateErrorText }

-  val instanceId: StateFlow<String> = runtime.instanceId
-  val displayName: StateFlow<String> = runtime.displayName
-  val cameraEnabled: StateFlow<Boolean> = runtime.cameraEnabled
-  val locationMode: StateFlow<LocationMode> = runtime.locationMode
-  val locationPreciseEnabled: StateFlow<Boolean> = runtime.locationPreciseEnabled
-  val preventSleep: StateFlow<Boolean> = runtime.preventSleep
-  val micEnabled: StateFlow<Boolean> = runtime.micEnabled
-  val micCooldown: StateFlow<Boolean> = runtime.micCooldown
-  val micStatusText: StateFlow<String> = runtime.micStatusText
-  val micLiveTranscript: StateFlow<String?> = runtime.micLiveTranscript
-  val micIsListening: StateFlow<Boolean> = runtime.micIsListening
-  val micQueuedMessages: StateFlow<List<String>> = runtime.micQueuedMessages
-  val micConversation: StateFlow<List<VoiceConversationEntry>> = runtime.micConversation
-  val micInputLevel: StateFlow<Float> = runtime.micInputLevel
-  val micIsSending: StateFlow<Boolean> = runtime.micIsSending
-  val speakerEnabled: StateFlow<Boolean> = runtime.speakerEnabled
-  val manualEnabled: StateFlow<Boolean> = runtime.manualEnabled
-  val manualHost: StateFlow<String> = runtime.manualHost
-  val manualPort: StateFlow<Int> = runtime.manualPort
-  val manualTls: StateFlow<Boolean> = runtime.manualTls
-  val gatewayToken: StateFlow<String> = runtime.gatewayToken
-  val onboardingCompleted: StateFlow<Boolean> = runtime.onboardingCompleted
-  val canvasDebugStatusEnabled: StateFlow<Boolean> = runtime.canvasDebugStatusEnabled
+  val gateways: StateFlow<List<GatewayEndpoint>> = runtimeState(initial = emptyList()) { it.gateways }
+  val discoveryStatusText: StateFlow<String> = runtimeState(initial = "Searching…") { it.discoveryStatusText }

-  val chatSessionKey: StateFlow<String> = runtime.chatSessionKey
-  val chatSessionId: StateFlow<String?> = runtime.chatSessionId
-  val chatMessages = runtime.chatMessages
-  val chatError: StateFlow<String?> = runtime.chatError
-  val chatHealthOk: StateFlow<Boolean> = runtime.chatHealthOk
-  val chatThinkingLevel: StateFlow<String> = runtime.chatThinkingLevel
-  val chatStreamingAssistantText: StateFlow<String?> = runtime.chatStreamingAssistantText
-  val chatPendingToolCalls = runtime.chatPendingToolCalls
-  val chatSessions = runtime.chatSessions
-  val pendingRunCount: StateFlow<Int> = runtime.pendingRunCount
+  val isConnected: StateFlow<Boolean> = runtimeState(initial = false) { it.isConnected }
+  val isNodeConnected: StateFlow<Boolean> = runtimeState(initial = false) { it.nodeConnected }
+  val statusText: StateFlow<String> = runtimeState(initial = "Offline") { it.statusText }
+  val serverName: StateFlow<String?> = runtimeState(initial = null) { it.serverName }
+  val remoteAddress: StateFlow<String?> = runtimeState(initial = null) { it.remoteAddress }
+  val pendingGatewayTrust: StateFlow<NodeRuntime.GatewayTrustPrompt?> = runtimeState(initial = null) { it.pendingGatewayTrust }
+  val seamColorArgb: StateFlow<Long> = runtimeState(initial = 0xFF0EA5E9) { it.seamColorArgb }
+  val mainSessionKey: StateFlow<String> = runtimeState(initial = "main") { it.mainSessionKey }
+
+  val cameraHud: StateFlow<CameraHudState?> = runtimeState(initial = null) { it.cameraHud }
+  val cameraFlashToken: StateFlow<Long> = runtimeState(initial = 0L) { it.cameraFlashToken }
+
+  val instanceId: StateFlow<String> = prefs.instanceId
+  val displayName: StateFlow<String> = prefs.displayName
+  val cameraEnabled: StateFlow<Boolean> = prefs.cameraEnabled
+  val locationMode: StateFlow<LocationMode> = prefs.locationMode
+  val locationPreciseEnabled: StateFlow<Boolean> = prefs.locationPreciseEnabled
+  val preventSleep: StateFlow<Boolean> = prefs.preventSleep
+  val manualEnabled: StateFlow<Boolean> = prefs.manualEnabled
+  val manualHost: StateFlow<String> = prefs.manualHost
+  val manualPort: StateFlow<Int> = prefs.manualPort
+  val manualTls: StateFlow<Boolean> = prefs.manualTls
+  val gatewayToken: StateFlow<String> = prefs.gatewayToken
+  val onboardingCompleted: StateFlow<Boolean> = prefs.onboardingCompleted
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = prefs.canvasDebugStatusEnabled
+  val speakerEnabled: StateFlow<Boolean> = prefs.speakerEnabled
+  val micEnabled: StateFlow<Boolean> = prefs.talkEnabled
+
+  val micCooldown: StateFlow<Boolean> = runtimeState(initial = false) { it.micCooldown }
+  val micStatusText: StateFlow<String> = runtimeState(initial = "Mic off") { it.micStatusText }
+  val micLiveTranscript: StateFlow<String?> = runtimeState(initial = null) { it.micLiveTranscript }
+  val micIsListening: StateFlow<Boolean> = runtimeState(initial = false) { it.micIsListening }
+  val micQueuedMessages: StateFlow<List<String>> = runtimeState(initial = emptyList()) { it.micQueuedMessages }
+  val micConversation: StateFlow<List<VoiceConversationEntry>> = runtimeState(initial = emptyList()) { it.micConversation }
+  val micInputLevel: StateFlow<Float> = runtimeState(initial = 0f) { it.micInputLevel }
+  val micIsSending: StateFlow<Boolean> = runtimeState(initial = false) { it.micIsSending }
+
+  val chatSessionKey: StateFlow<String> = runtimeState(initial = "main") { it.chatSessionKey }
+  val chatSessionId: StateFlow<String?> = runtimeState(initial = null) { it.chatSessionId }
+  val chatMessages: StateFlow<List<ChatMessage>> = runtimeState(initial = emptyList()) { it.chatMessages }
+  val chatError: StateFlow<String?> = runtimeState(initial = null) { it.chatError }
+  val chatHealthOk: StateFlow<Boolean> = runtimeState(initial = false) { it.chatHealthOk }
+  val chatThinkingLevel: StateFlow<String> = runtimeState(initial = "off") { it.chatThinkingLevel }
+  val chatStreamingAssistantText: StateFlow<String?> = runtimeState(initial = null) { it.chatStreamingAssistantText }
+  val chatPendingToolCalls: StateFlow<List<ChatPendingToolCall>> = runtimeState(initial = emptyList()) { it.chatPendingToolCalls }
+  val chatSessions: StateFlow<List<ChatSessionEntry>> = runtimeState(initial = emptyList()) { it.chatSessions }
+  val pendingRunCount: StateFlow<Int> = runtimeState(initial = 0) { it.pendingRunCount }
+
+  init {
+    if (prefs.onboardingCompleted.value) {
+      ensureRuntime()
+    }
+  }
+
+  val canvas: CanvasController
+    get() = ensureRuntime().canvas
+
+  val camera: CameraCaptureManager
+    get() = ensureRuntime().camera
+
+  val sms: SmsManager
+    get() = ensureRuntime().sms
+
+  fun attachRuntimeUi(owner: LifecycleOwner, permissionRequester: PermissionRequester) {
+    val runtime = runtimeRef.value ?: return
+    runtime.camera.attachLifecycleOwner(owner)
+    runtime.camera.attachPermissionRequester(permissionRequester)
+    runtime.sms.attachPermissionRequester(permissionRequester)
+  }

  fun setForeground(value: Boolean) {
-    runtime.setForeground(value)
+    foreground = value
+    runtimeRef.value?.setForeground(value)
  }

  fun setDisplayName(value: String) {
-    runtime.setDisplayName(value)
+    prefs.setDisplayName(value)
  }

  fun setCameraEnabled(value: Boolean) {
-    runtime.setCameraEnabled(value)
+    prefs.setCameraEnabled(value)
  }

  fun setLocationMode(mode: LocationMode) {
-    runtime.setLocationMode(mode)
+    prefs.setLocationMode(mode)
  }

  fun setLocationPreciseEnabled(value: Boolean) {
-    runtime.setLocationPreciseEnabled(value)
+    prefs.setLocationPreciseEnabled(value)
  }

  fun setPreventSleep(value: Boolean) {
-    runtime.setPreventSleep(value)
+    prefs.setPreventSleep(value)
  }

  fun setManualEnabled(value: Boolean) {
-    runtime.setManualEnabled(value)
+    prefs.setManualEnabled(value)
  }

  fun setManualHost(value: String) {
-    runtime.setManualHost(value)
+    prefs.setManualHost(value)
  }

  fun setManualPort(value: Int) {
-    runtime.setManualPort(value)
+    prefs.setManualPort(value)
  }

  fun setManualTls(value: Boolean) {
-    runtime.setManualTls(value)
+    prefs.setManualTls(value)
  }

  fun setGatewayToken(value: String) {
-    runtime.setGatewayToken(value)
+    prefs.setGatewayToken(value)
  }

  fun setGatewayBootstrapToken(value: String) {
-    runtime.setGatewayBootstrapToken(value)
+    prefs.setGatewayBootstrapToken(value)
  }

  fun setGatewayPassword(value: String) {
-    runtime.setGatewayPassword(value)
+    prefs.setGatewayPassword(value)
  }

  fun setOnboardingCompleted(value: Boolean) {
-    runtime.setOnboardingCompleted(value)
+    if (value) {
+      ensureRuntime()
+    }
+    prefs.setOnboardingCompleted(value)
  }

  fun setCanvasDebugStatusEnabled(value: Boolean) {
-    runtime.setCanvasDebugStatusEnabled(value)
+    prefs.setCanvasDebugStatusEnabled(value)
  }

  fun setVoiceScreenActive(active: Boolean) {
-    runtime.setVoiceScreenActive(active)
+    ensureRuntime().setVoiceScreenActive(active)
  }

  fun setMicEnabled(enabled: Boolean) {
-    runtime.setMicEnabled(enabled)
+    ensureRuntime().setMicEnabled(enabled)
  }

  fun setSpeakerEnabled(enabled: Boolean) {
-    runtime.setSpeakerEnabled(enabled)
+    ensureRuntime().setSpeakerEnabled(enabled)
  }

  fun refreshGatewayConnection() {
-    runtime.refreshGatewayConnection()
+    ensureRuntime().refreshGatewayConnection()
  }

  fun connect(endpoint: GatewayEndpoint) {
-    runtime.connect(endpoint)
+    ensureRuntime().connect(endpoint)
  }

  fun connectManual() {
-    runtime.connectManual()
+    ensureRuntime().connectManual()
  }

  fun disconnect() {
-    runtime.disconnect()
+    runtimeRef.value?.disconnect()
  }

  fun acceptGatewayTrustPrompt() {
-    runtime.acceptGatewayTrustPrompt()
+    runtimeRef.value?.acceptGatewayTrustPrompt()
  }

  fun declineGatewayTrustPrompt() {
-    runtime.declineGatewayTrustPrompt()
+    runtimeRef.value?.declineGatewayTrustPrompt()
  }

  fun handleCanvasA2UIActionFromWebView(payloadJson: String) {
-    runtime.handleCanvasA2UIActionFromWebView(payloadJson)
+    ensureRuntime().handleCanvasA2UIActionFromWebView(payloadJson)
  }

  fun requestCanvasRehydrate(source: String = "screen_tab") {
-    runtime.requestCanvasRehydrate(source = source, force = true)
+    ensureRuntime().requestCanvasRehydrate(source = source, force = true)
  }

  fun refreshHomeCanvasOverviewIfConnected() {
-    runtime.refreshHomeCanvasOverviewIfConnected()
+    ensureRuntime().refreshHomeCanvasOverviewIfConnected()
  }

  fun loadChat(sessionKey: String) {
-    runtime.loadChat(sessionKey)
+    ensureRuntime().loadChat(sessionKey)
  }

  fun refreshChat() {
-    runtime.refreshChat()
+    ensureRuntime().refreshChat()
  }

  fun refreshChatSessions(limit: Int? = null) {
-    runtime.refreshChatSessions(limit = limit)
+    ensureRuntime().refreshChatSessions(limit = limit)
  }

  fun setChatThinkingLevel(level: String) {
-    runtime.setChatThinkingLevel(level)
+    ensureRuntime().setChatThinkingLevel(level)
  }

  fun switchChatSession(sessionKey: String) {
-    runtime.switchChatSession(sessionKey)
+    ensureRuntime().switchChatSession(sessionKey)
  }

  fun abortChat() {
-    runtime.abortChat()
+    ensureRuntime().abortChat()
  }

  fun sendChat(message: String, thinking: String, attachments: List<OutgoingAttachment>) {
-    runtime.sendChat(message = message, thinking = thinking, attachments = attachments)
+    ensureRuntime().sendChat(message = message, thinking = thinking, attachments = attachments)
  }
 }
--- a/apps/android/app/src/main/java/ai/openclaw/app/NodeApp.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/NodeApp.kt
@ -4,7 +4,18 @@ import android.app.Application
 import android.os.StrictMode

 class NodeApp : Application() {
-  val runtime: NodeRuntime by lazy { NodeRuntime(this) }
+  val prefs: SecurePrefs by lazy { SecurePrefs(this) }
+
+  @Volatile private var runtimeInstance: NodeRuntime? = null
+
+  fun ensureRuntime(): NodeRuntime {
+    runtimeInstance?.let { return it }
+    return synchronized(this) {
+      runtimeInstance ?: NodeRuntime(this, prefs).also { runtimeInstance = it }
+    }
+  }
+
+  fun peekRuntime(): NodeRuntime? = runtimeInstance

  override fun onCreate() {
    super.onCreate()
--- a/apps/android/app/src/main/java/ai/openclaw/app/NodeForegroundService.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/NodeForegroundService.kt
@ -28,7 +28,11 @@ class NodeForegroundService : Service() {
    val initial = buildNotification(title = "OpenClaw Node", text = "Starting…")
    startForegroundWithTypes(notification = initial)

-    val runtime = (application as NodeApp).runtime
+    val runtime = (application as NodeApp).peekRuntime()
+    if (runtime == null) {
+      stopSelf()
+      return
+    }
    notificationJob =
      scope.launch {
        combine(
@ -59,7 +63,7 @@ class NodeForegroundService : Service() {
  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
    when (intent?.action) {
      ACTION_STOP -> {
-        (application as NodeApp).runtime.disconnect()
+        (application as NodeApp).peekRuntime()?.disconnect()
        stopSelf()
        return START_NOT_STICKY
      }
--- a/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt
@ -43,11 +43,12 @@ import kotlinx.serialization.json.buildJsonObject
 import java.util.UUID
 import java.util.concurrent.atomic.AtomicLong

-class NodeRuntime(context: Context) {
+class NodeRuntime(
+  context: Context,
+  val prefs: SecurePrefs = SecurePrefs(context.applicationContext),
+) {
  private val appContext = context.applicationContext
  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
-
-  val prefs = SecurePrefs(appContext)
  private val deviceAuthStore = DeviceAuthStore(prefs)
  val canvas = CanvasController()
  val camera = CameraCaptureManager(appContext)
--- a/apps/android/app/src/main/java/ai/openclaw/app/chat/ChatController.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/chat/ChatController.kt
@ -265,7 +265,7 @@ class ChatController(
      }

      val historyJson = session.request("chat.history", """{"sessionKey":"$key"}""")
-      val history = parseHistory(historyJson, sessionKey = key)
+      val history = parseHistory(historyJson, sessionKey = key, previousMessages = _messages.value)
      _messages.value = history.messages
      _sessionId.value = history.sessionId
      history.thinkingLevel?.trim()?.takeIf { it.isNotEmpty() }?.let { _thinkingLevel.value = it }
@ -336,7 +336,7 @@ class ChatController(
          try {
            val historyJson =
              session.request("chat.history", """{"sessionKey":"${_sessionKey.value}"}""")
-            val history = parseHistory(historyJson, sessionKey = _sessionKey.value)
+            val history = parseHistory(historyJson, sessionKey = _sessionKey.value, previousMessages = _messages.value)
            _messages.value = history.messages
            _sessionId.value = history.sessionId
            history.thinkingLevel?.trim()?.takeIf { it.isNotEmpty() }?.let { _thinkingLevel.value = it }
@ -450,7 +450,11 @@ class ChatController(
    }
  }

-  private fun parseHistory(historyJson: String, sessionKey: String): ChatHistory {
+  private fun parseHistory(
+    historyJson: String,
+    sessionKey: String,
+    previousMessages: List<ChatMessage>,
+  ): ChatHistory {
    val root = json.parseToJsonElement(historyJson).asObjectOrNull() ?: return ChatHistory(sessionKey, null, null, emptyList())
    val sid = root["sessionId"].asStringOrNull()
    val thinkingLevel = root["thinkingLevel"].asStringOrNull()
@ -470,7 +474,12 @@ class ChatController(
        )
      }

-    return ChatHistory(sessionKey = sessionKey, sessionId = sid, thinkingLevel = thinkingLevel, messages = messages)
+    return ChatHistory(
+      sessionKey = sessionKey,
+      sessionId = sid,
+      thinkingLevel = thinkingLevel,
+      messages = reconcileMessageIds(previous = previousMessages, incoming = messages),
+    )
  }

  private fun parseMessageContent(el: JsonElement): ChatMessageContent? {
@ -519,6 +528,47 @@ class ChatController(
  }
 }

+internal fun reconcileMessageIds(previous: List<ChatMessage>, incoming: List<ChatMessage>): List<ChatMessage> {
+  if (previous.isEmpty() || incoming.isEmpty()) return incoming
+
+  val idsByKey = LinkedHashMap<String, ArrayDeque<String>>()
+  for (message in previous) {
+    val key = messageIdentityKey(message) ?: continue
+    idsByKey.getOrPut(key) { ArrayDeque() }.addLast(message.id)
+  }
+
+  return incoming.map { message ->
+    val key = messageIdentityKey(message) ?: return@map message
+    val ids = idsByKey[key] ?: return@map message
+    val reusedId = ids.removeFirstOrNull() ?: return@map message
+    if (ids.isEmpty()) {
+      idsByKey.remove(key)
+    }
+    if (reusedId == message.id) return@map message
+    message.copy(id = reusedId)
+  }
+}
+
+internal fun messageIdentityKey(message: ChatMessage): String? {
+  val role = message.role.trim().lowercase()
+  if (role.isEmpty()) return null
+
+  val timestamp = message.timestampMs?.toString().orEmpty()
+  val contentFingerprint =
+    message.content.joinToString(separator = "\u001E") { part ->
+      listOf(
+        part.type.trim().lowercase(),
+        part.text?.trim().orEmpty(),
+        part.mimeType?.trim()?.lowercase().orEmpty(),
+        part.fileName?.trim().orEmpty(),
+        part.base64?.hashCode()?.toString().orEmpty(),
+      ).joinToString(separator = "\u001F")
+    }
+
+  if (timestamp.isEmpty() && contentFingerprint.isEmpty()) return null
+  return listOf(role, timestamp, contentFingerprint).joinToString(separator = "|")
+}
+
 private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject

 private fun JsonElement?.asArrayOrNull(): JsonArray? = this as? JsonArray
--- a/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/Base64ImageState.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/Base64ImageState.kt
@ -1,7 +1,5 @@
 package ai.openclaw.app.ui.chat

-import android.graphics.BitmapFactory
-import android.util.Base64
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
@ -28,8 +26,7 @@ internal fun rememberBase64ImageState(base64: String): Base64ImageState {
    image =
      withContext(Dispatchers.Default) {
        try {
-          val bytes = Base64.decode(base64, Base64.DEFAULT)
-          val bitmap = BitmapFactory.decodeByteArray(bytes, 0, bytes.size) ?: return@withContext null
+          val bitmap = decodeBase64Bitmap(base64) ?: return@withContext null
          bitmap.asImageBitmap()
        } catch (_: Throwable) {
          null
--- a/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatImageCodec.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatImageCodec.kt
@ -0,0 +1,150 @@
+package ai.openclaw.app.ui.chat
+
+import android.content.ContentResolver
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.util.Base64
+import android.util.LruCache
+import androidx.core.graphics.scale
+import ai.openclaw.app.node.JpegSizeLimiter
+import java.io.ByteArrayOutputStream
+import kotlin.math.max
+import kotlin.math.roundToInt
+
+private const val CHAT_ATTACHMENT_MAX_WIDTH = 1600
+private const val CHAT_ATTACHMENT_MAX_BASE64_CHARS = 300 * 1024
+private const val CHAT_ATTACHMENT_START_QUALITY = 85
+private const val CHAT_DECODE_MAX_DIMENSION = 1600
+private const val CHAT_IMAGE_CACHE_BYTES = 16 * 1024 * 1024
+
+private val decodedBitmapCache =
+  object : LruCache<String, Bitmap>(CHAT_IMAGE_CACHE_BYTES) {
+    override fun sizeOf(key: String, value: Bitmap): Int = value.byteCount.coerceAtLeast(1)
+  }
+
+internal fun loadSizedImageAttachment(resolver: ContentResolver, uri: Uri): PendingImageAttachment {
+  val fileName = normalizeAttachmentFileName((uri.lastPathSegment ?: "image").substringAfterLast('/'))
+  val bitmap = decodeScaledBitmap(resolver, uri, maxDimension = CHAT_ATTACHMENT_MAX_WIDTH)
+  if (bitmap == null) {
+    throw IllegalStateException("unsupported attachment")
+  }
+  val maxBytes = (CHAT_ATTACHMENT_MAX_BASE64_CHARS / 4) * 3
+  val encoded =
+    JpegSizeLimiter.compressToLimit(
+      initialWidth = bitmap.width,
+      initialHeight = bitmap.height,
+      startQuality = CHAT_ATTACHMENT_START_QUALITY,
+      maxBytes = maxBytes,
+      minSize = 240,
+      encode = { width, height, quality ->
+        val working =
+          if (width == bitmap.width && height == bitmap.height) {
+            bitmap
+          } else {
+            bitmap.scale(width, height, true)
+          }
+        try {
+          val out = ByteArrayOutputStream()
+          if (!working.compress(Bitmap.CompressFormat.JPEG, quality, out)) {
+            throw IllegalStateException("attachment encode failed")
+          }
+          out.toByteArray()
+        } finally {
+          if (working !== bitmap) {
+            working.recycle()
+          }
+        }
+      },
+    )
+  val base64 = Base64.encodeToString(encoded.bytes, Base64.NO_WRAP)
+  return PendingImageAttachment(
+    id = uri.toString() + "#" + System.currentTimeMillis().toString(),
+    fileName = fileName,
+    mimeType = "image/jpeg",
+    base64 = base64,
+  )
+}
+
+internal fun decodeBase64Bitmap(base64: String, maxDimension: Int = CHAT_DECODE_MAX_DIMENSION): Bitmap? {
+  val cacheKey = "$maxDimension:${base64.length}:${base64.hashCode()}"
+  decodedBitmapCache.get(cacheKey)?.let { return it }
+
+  val bytes = Base64.decode(base64, Base64.DEFAULT)
+  if (bytes.isEmpty()) return null
+
+  val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+  BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+  if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+  val bitmap =
+    BitmapFactory.decodeByteArray(
+      bytes,
+      0,
+      bytes.size,
+      BitmapFactory.Options().apply {
+        inSampleSize = computeInSampleSize(bounds.outWidth, bounds.outHeight, maxDimension)
+        inPreferredConfig = Bitmap.Config.RGB_565
+      },
+    ) ?: return null
+
+  decodedBitmapCache.put(cacheKey, bitmap)
+  return bitmap
+}
+
+internal fun computeInSampleSize(width: Int, height: Int, maxDimension: Int): Int {
+  if (width <= 0 || height <= 0 || maxDimension <= 0) return 1
+
+  var sample = 1
+  var longestEdge = max(width, height)
+  while (longestEdge > maxDimension && sample < 64) {
+    sample *= 2
+    longestEdge = max(width / sample, height / sample)
+  }
+  return sample.coerceAtLeast(1)
+}
+
+internal fun normalizeAttachmentFileName(raw: String): String {
+  val trimmed = raw.trim()
+  if (trimmed.isEmpty()) return "image.jpg"
+  val stem = trimmed.substringBeforeLast('.', missingDelimiterValue = trimmed).ifEmpty { "image" }
+  return "$stem.jpg"
+}
+
+private fun decodeScaledBitmap(
+  resolver: ContentResolver,
+  uri: Uri,
+  maxDimension: Int,
+): Bitmap? {
+  val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+  resolver.openInputStream(uri).use { input ->
+    if (input == null) return null
+    BitmapFactory.decodeStream(input, null, bounds)
+  }
+  if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+  val decoded =
+    resolver.openInputStream(uri).use { input ->
+      if (input == null) return null
+      BitmapFactory.decodeStream(
+        input,
+        null,
+        BitmapFactory.Options().apply {
+          inSampleSize = computeInSampleSize(bounds.outWidth, bounds.outHeight, maxDimension)
+          inPreferredConfig = Bitmap.Config.ARGB_8888
+        },
+      )
+    } ?: return null
+
+  val longestEdge = max(decoded.width, decoded.height)
+  if (longestEdge <= maxDimension) return decoded
+
+  val scale = maxDimension.toDouble() / longestEdge.toDouble()
+  val targetWidth = max(1, (decoded.width * scale).roundToInt())
+  val targetHeight = max(1, (decoded.height * scale).roundToInt())
+  val scaled = decoded.scale(targetWidth, targetHeight, true)
+  if (scaled !== decoded) {
+    decoded.recycle()
+  }
+  return scaled
+}
--- a/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatMessageListCard.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatMessageListCard.kt
@ -6,12 +6,14 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
 import androidx.compose.foundation.lazy.rememberLazyListState
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.remember
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.unit.dp
@ -34,11 +36,19 @@ fun ChatMessageListCard(
  modifier: Modifier = Modifier,
 ) {
  val listState = rememberLazyListState()
+  val displayMessages = remember(messages) { messages.asReversed() }
+  val stream = streamingAssistantText?.trim()

-  // With reverseLayout the newest item is at index 0 (bottom of screen).
-  LaunchedEffect(messages.size, pendingRunCount, pendingToolCalls.size, streamingAssistantText) {
+  // New list items/tool rows should animate into view, but token streaming should not restart
+  // that animation on every delta.
+  LaunchedEffect(messages.size, pendingRunCount, pendingToolCalls.size) {
    listState.animateScrollToItem(index = 0)
  }
+  LaunchedEffect(stream) {
+    if (!stream.isNullOrEmpty()) {
+      listState.scrollToItem(index = 0)
+    }
+  }

  Box(modifier = modifier.fillMaxWidth()) {
    LazyColumn(
@ -50,8 +60,6 @@ fun ChatMessageListCard(
    ) {
      // With reverseLayout = true, index 0 renders at the BOTTOM.
      // So we emit newest items first: streaming → tools → typing → messages (newest→oldest).
-
-      val stream = streamingAssistantText?.trim()
      if (!stream.isNullOrEmpty()) {
        item(key = "stream") {
          ChatStreamingAssistantBubble(text = stream)
@ -70,8 +78,8 @@ fun ChatMessageListCard(
        }
      }

-      items(count = messages.size, key = { idx -> messages[messages.size - 1 - idx].id }) { idx ->
-        ChatMessageBubble(message = messages[messages.size - 1 - idx])
+      items(items = displayMessages, key = { it.id }) { message ->
+        ChatMessageBubble(message = message)
      }
    }

--- a/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatSheetContent.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatSheetContent.kt
@ -1,8 +1,5 @@
 package ai.openclaw.app.ui.chat

-import android.content.ContentResolver
-import android.net.Uri
-import android.util.Base64
 import androidx.activity.compose.rememberLauncherForActivityResult
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.foundation.BorderStroke
@ -47,7 +44,6 @@ import ai.openclaw.app.ui.mobileDanger
 import ai.openclaw.app.ui.mobileDangerSoft
 import ai.openclaw.app.ui.mobileText
 import ai.openclaw.app.ui.mobileTextSecondary
-import java.io.ByteArrayOutputStream
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
@ -83,7 +79,7 @@ fun ChatSheetContent(viewModel: MainViewModel) {
        val next =
          uris.take(8).mapNotNull { uri ->
            try {
-              loadImageAttachment(resolver, uri)
+              loadSizedImageAttachment(resolver, uri)
            } catch (_: Throwable) {
              null
            }
@ -160,7 +156,10 @@ private fun ChatThreadSelector(
  mainSessionKey: String,
  onSelectSession: (String) -> Unit,
 ) {
-  val sessionOptions = resolveSessionChoices(sessionKey, sessions, mainSessionKey = mainSessionKey)
+  val sessionOptions =
+    remember(sessionKey, sessions, mainSessionKey) {
+      resolveSessionChoices(sessionKey, sessions, mainSessionKey = mainSessionKey)
+    }

  Row(
    modifier = Modifier.fillMaxWidth().horizontalScroll(rememberScrollState()),
@ -214,24 +213,3 @@ data class PendingImageAttachment(
  val mimeType: String,
  val base64: String,
 )
-
-private suspend fun loadImageAttachment(resolver: ContentResolver, uri: Uri): PendingImageAttachment {
-  val mimeType = resolver.getType(uri) ?: "image/*"
-  val fileName = (uri.lastPathSegment ?: "image").substringAfterLast('/')
-  val bytes =
-    withContext(Dispatchers.IO) {
-      resolver.openInputStream(uri)?.use { input ->
-        val out = ByteArrayOutputStream()
-        input.copyTo(out)
-        out.toByteArray()
-      } ?: ByteArray(0)
-    }
-  if (bytes.isEmpty()) throw IllegalStateException("empty attachment")
-  val base64 = Base64.encodeToString(bytes, Base64.NO_WRAP)
-  return PendingImageAttachment(
-    id = uri.toString() + "#" + System.currentTimeMillis().toString(),
-    fileName = fileName,
-    mimeType = mimeType,
-    base64 = base64,
-  )
-}
--- a/apps/android/app/src/test/java/ai/openclaw/app/chat/ChatControllerMessageIdentityTest.kt
+++ b/apps/android/app/src/test/java/ai/openclaw/app/chat/ChatControllerMessageIdentityTest.kt
@ -0,0 +1,81 @@
+package ai.openclaw.app.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Test
+
+class ChatControllerMessageIdentityTest {
+  @Test
+  fun reconcileMessageIdsReusesMatchingIdsAcrossHistoryReload() {
+    val previous =
+      listOf(
+        ChatMessage(
+          id = "msg-1",
+          role = "assistant",
+          content = listOf(ChatMessageContent(type = "text", text = "hello")),
+          timestampMs = 1000L,
+        ),
+        ChatMessage(
+          id = "msg-2",
+          role = "user",
+          content = listOf(ChatMessageContent(type = "text", text = "hi")),
+          timestampMs = 2000L,
+        ),
+      )
+
+    val incoming =
+      listOf(
+        ChatMessage(
+          id = "new-1",
+          role = "assistant",
+          content = listOf(ChatMessageContent(type = "text", text = "hello")),
+          timestampMs = 1000L,
+        ),
+        ChatMessage(
+          id = "new-2",
+          role = "user",
+          content = listOf(ChatMessageContent(type = "text", text = "hi")),
+          timestampMs = 2000L,
+        ),
+      )
+
+    val reconciled = reconcileMessageIds(previous = previous, incoming = incoming)
+
+    assertEquals(listOf("msg-1", "msg-2"), reconciled.map { it.id })
+  }
+
+  @Test
+  fun reconcileMessageIdsLeavesNewMessagesUntouched() {
+    val previous =
+      listOf(
+        ChatMessage(
+          id = "msg-1",
+          role = "assistant",
+          content = listOf(ChatMessageContent(type = "text", text = "hello")),
+          timestampMs = 1000L,
+        ),
+      )
+
+    val incoming =
+      listOf(
+        ChatMessage(
+          id = "new-1",
+          role = "assistant",
+          content = listOf(ChatMessageContent(type = "text", text = "hello")),
+          timestampMs = 1000L,
+        ),
+        ChatMessage(
+          id = "new-2",
+          role = "assistant",
+          content = listOf(ChatMessageContent(type = "text", text = "new reply")),
+          timestampMs = 3000L,
+        ),
+      )
+
+    val reconciled = reconcileMessageIds(previous = previous, incoming = incoming)
+
+    assertEquals("msg-1", reconciled[0].id)
+    assertEquals("new-2", reconciled[1].id)
+    assertNotEquals(reconciled[0].id, reconciled[1].id)
+  }
+}
--- a/apps/android/app/src/test/java/ai/openclaw/app/ui/chat/ChatImageCodecTest.kt
+++ b/apps/android/app/src/test/java/ai/openclaw/app/ui/chat/ChatImageCodecTest.kt
@ -0,0 +1,18 @@
+package ai.openclaw.app.ui.chat
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class ChatImageCodecTest {
+  @Test
+  fun computeInSampleSizeCapsLongestEdge() {
+    assertEquals(4, computeInSampleSize(width = 4032, height = 3024, maxDimension = 1600))
+    assertEquals(1, computeInSampleSize(width = 800, height = 600, maxDimension = 1600))
+  }
+
+  @Test
+  fun normalizeAttachmentFileNameForcesJpegExtension() {
+    assertEquals("photo.jpg", normalizeAttachmentFileName("photo.png"))
+    assertEquals("image.jpg", normalizeAttachmentFileName(""))
+  }
+}
--- a/docs/.generated/config-baseline.json
+++ b/docs/.generated/config-baseline.json
@ -8035,7 +8035,21 @@
        "storage"
      ],
      "label": "Browser Profile Driver",
-      "help": "Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome MCP attachment.",
+      "help": "Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome DevTools MCP attachment.",
+      "hasChildren": false
+    },
+    {
+      "path": "browser.profiles.*.userDataDir",
+      "kind": "core",
+      "type": "string",
+      "required": false,
+      "deprecated": false,
+      "sensitive": false,
+      "tags": [
+        "storage"
+      ],
+      "label": "Browser Profile User Data Dir",
+      "help": "Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for host-local Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory.",
      "hasChildren": false
    },
    {
@ -32140,6 +32154,16 @@
      "tags": [],
      "hasChildren": false
    },
+    {
+      "path": "channels.telegram.accounts.*.silentErrorReplies",
+      "kind": "channel",
+      "type": "boolean",
+      "required": false,
+      "deprecated": false,
+      "sensitive": false,
+      "tags": [],
+      "hasChildren": false
+    },
    {
      "path": "channels.telegram.accounts.*.streaming",
      "kind": "channel",
@ -34137,6 +34161,21 @@
      "help": "Minimum retry delay in ms for Telegram outbound calls.",
      "hasChildren": false
    },
+    {
+      "path": "channels.telegram.silentErrorReplies",
+      "kind": "channel",
+      "type": "boolean",
+      "required": false,
+      "deprecated": false,
+      "sensitive": false,
+      "tags": [
+        "channels",
+        "network"
+      ],
+      "label": "Telegram Silent Error Replies",
+      "help": "When true, Telegram bot replies marked as errors are sent silently (no notification sound). Default: false.",
+      "hasChildren": false
+    },
    {
      "path": "channels.telegram.streaming",
      "kind": "channel",
--- a/docs/.generated/config-baseline.jsonl
+++ b/docs/.generated/config-baseline.jsonl
@ -1,4 +1,4 @@
-{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5101}
+{"generatedBy":"scripts/generate-config-doc-baseline.ts","recordType":"meta","totalPaths":5104}
 {"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}
@ -707,7 +707,8 @@
 {"recordType":"path","path":"browser.profiles.*.cdpPort","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile CDP Port","help":"Per-profile local CDP port used when connecting to browser instances by port instead of URL. Use unique ports per profile to avoid connection collisions.","hasChildren":false}
 {"recordType":"path","path":"browser.profiles.*.cdpUrl","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile CDP URL","help":"Per-profile CDP websocket URL used for explicit remote browser routing by profile name. Use this when profile connections terminate on remote hosts or tunnels.","hasChildren":false}
 {"recordType":"path","path":"browser.profiles.*.color","kind":"core","type":"string","required":true,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Accent Color","help":"Per-profile accent color for visual differentiation in dashboards and browser-related UI hints. Use distinct colors for high-signal operator recognition of active profiles.","hasChildren":false}
-{"recordType":"path","path":"browser.profiles.*.driver","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Driver","help":"Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome MCP attachment.","hasChildren":false}
+{"recordType":"path","path":"browser.profiles.*.driver","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile Driver","help":"Per-profile browser driver mode. Use \"openclaw\" (or legacy \"clawd\") for CDP-based profiles, or use \"existing-session\" for host-local Chrome DevTools MCP attachment.","hasChildren":false}
+{"recordType":"path","path":"browser.profiles.*.userDataDir","kind":"core","type":"string","required":false,"deprecated":false,"sensitive":false,"tags":["storage"],"label":"Browser Profile User Data Dir","help":"Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for host-local Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory.","hasChildren":false}
 {"recordType":"path","path":"browser.remoteCdpHandshakeTimeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Remote CDP Handshake Timeout (ms)","help":"Timeout in milliseconds for post-connect CDP handshake readiness checks against remote browser targets. Raise this for slow-start remote browsers and lower to fail fast in automation loops.","hasChildren":false}
 {"recordType":"path","path":"browser.remoteCdpTimeoutMs","kind":"core","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["performance"],"label":"Remote CDP Timeout (ms)","help":"Timeout in milliseconds for connecting to a remote CDP endpoint before failing the browser attach attempt. Increase for high-latency tunnels, or lower for faster failure detection.","hasChildren":false}
 {"recordType":"path","path":"browser.snapshotDefaults","kind":"core","type":"object","required":false,"deprecated":false,"sensitive":false,"tags":["advanced"],"label":"Browser Snapshot Defaults","help":"Default snapshot capture configuration used when callers do not provide explicit snapshot options. Tune this for consistent capture behavior across channels and automation paths.","hasChildren":true}
@ -2903,6 +2904,7 @@
 {"recordType":"path","path":"channels.telegram.accounts.*.retry.jitter","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.accounts.*.retry.maxDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.accounts.*.retry.minDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
+{"recordType":"path","path":"channels.telegram.accounts.*.silentErrorReplies","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.accounts.*.streaming","kind":"channel","type":["boolean","string"],"required":false,"enumValues":["off","partial","block","progress"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.accounts.*.streamMode","kind":"channel","type":"string","required":false,"enumValues":["off","partial","block"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.accounts.*.textChunkLimit","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
@ -3080,6 +3082,7 @@
 {"recordType":"path","path":"channels.telegram.retry.jitter","kind":"channel","type":"number","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network","reliability"],"label":"Telegram Retry Jitter","help":"Jitter factor (0-1) applied to Telegram retry delays.","hasChildren":false}
 {"recordType":"path","path":"channels.telegram.retry.maxDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network","performance","reliability"],"label":"Telegram Retry Max Delay (ms)","help":"Maximum retry delay cap in ms for Telegram outbound calls.","hasChildren":false}
 {"recordType":"path","path":"channels.telegram.retry.minDelayMs","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network","reliability"],"label":"Telegram Retry Min Delay (ms)","help":"Minimum retry delay in ms for Telegram outbound calls.","hasChildren":false}
+{"recordType":"path","path":"channels.telegram.silentErrorReplies","kind":"channel","type":"boolean","required":false,"deprecated":false,"sensitive":false,"tags":["channels","network"],"label":"Telegram Silent Error Replies","help":"When true, Telegram bot replies marked as errors are sent silently (no notification sound). Default: false.","hasChildren":false}
 {"recordType":"path","path":"channels.telegram.streaming","kind":"channel","type":["boolean","string"],"required":false,"enumValues":["off","partial","block","progress"],"deprecated":false,"sensitive":false,"tags":["channels","network"],"label":"Telegram Streaming Mode","help":"Unified Telegram stream preview mode: \"off\" | \"partial\" | \"block\" | \"progress\" (default: \"partial\"). \"progress\" maps to \"partial\" on Telegram. Legacy boolean/streamMode keys are auto-mapped.","hasChildren":false}
 {"recordType":"path","path":"channels.telegram.streamMode","kind":"channel","type":"string","required":false,"enumValues":["off","partial","block"],"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
 {"recordType":"path","path":"channels.telegram.textChunkLimit","kind":"channel","type":"integer","required":false,"deprecated":false,"sensitive":false,"tags":[],"hasChildren":false}
--- a/docs/channels/bluebubbles.md
+++ b/docs/channels/bluebubbles.md
@ -126,7 +126,7 @@ launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

 ## Onboarding

-BlueBubbles is available in the interactive setup wizard:
+BlueBubbles is available in interactive onboarding:

 ```
 openclaw onboard
--- a/docs/channels/feishu.md
+++ b/docs/channels/feishu.md
@ -30,9 +30,9 @@ openclaw plugins install @openclaw/feishu

 There are two ways to add the Feishu channel:

-### Method 1: setup wizard (recommended)
+### Method 1: onboarding (recommended)

-If you just installed OpenClaw, run the setup wizard:
+If you just installed OpenClaw, run onboarding:

 ```bash
 openclaw onboard
--- a/docs/channels/nostr.md
+++ b/docs/channels/nostr.md
@ -16,7 +16,7 @@ Nostr is a decentralized protocol for social networking. This channel enables Op

 ### Onboarding (recommended)

- The setup wizard (`openclaw onboard`) and `openclaw channels add` list optional channel plugins.
+- Onboarding (`openclaw onboard`) and `openclaw channels add` list optional channel plugins.
 - Selecting Nostr prompts you to install the plugin on demand.

 Install defaults:
--- a/docs/channels/telegram.md
+++ b/docs/channels/telegram.md
@ -115,7 +115,7 @@ Token resolution order is account-aware. In practice, config values win over env

    `channels.telegram.allowFrom` accepts numeric Telegram user IDs. `telegram:` / `tg:` prefixes are accepted and normalized.
    `dmPolicy: "allowlist"` with empty `allowFrom` blocks all DMs and is rejected by config validation.
-    The setup wizard accepts `@username` input and resolves it to numeric IDs.
+    Onboarding accepts `@username` input and resolves it to numeric IDs.
    If you upgraded and your config contains `@username` allowlist entries, run `openclaw doctor --fix` to resolve them (best-effort; requires a Telegram bot token).
    If you previously relied on pairing-store allowlist files, `openclaw doctor --fix` can recover entries into `channels.telegram.allowFrom` in allowlist flows (for example when `dmPolicy: "allowlist"` has no explicit IDs yet).

--- a/docs/cli/browser.md
+++ b/docs/cli/browser.md
@ -91,6 +91,7 @@ Use the built-in `user` profile, or create your own `existing-session` profile:
 ```bash
 openclaw browser --browser-profile user tabs
 openclaw browser create-profile --name chrome-live --driver existing-session
+openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
 openclaw browser --browser-profile chrome-live tabs
 ```

--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@ -318,22 +318,22 @@ Initialize config + workspace.
 Options:

 - `--workspace <dir>`: agent workspace path (default `~/.openclaw/workspace`).
- `--wizard`: run the setup wizard.
- `--non-interactive`: run wizard without prompts.
- `--mode <local|remote>`: wizard mode.
+- `--wizard`: run onboarding.
+- `--non-interactive`: run onboarding without prompts.
+- `--mode <local|remote>`: onboard mode.
 - `--remote-url <url>`: remote Gateway URL.
 - `--remote-token <token>`: remote Gateway token.

-Wizard auto-runs when any wizard flags are present (`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).
+Onboarding auto-runs when any onboarding flags are present (`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).

 ### `onboard`

-Interactive wizard to set up gateway, workspace, and skills.
+Interactive onboarding for gateway, workspace, and skills.

 Options:

 - `--workspace <dir>`
- `--reset` (reset config + credentials + sessions before wizard)
+- `--reset` (reset config + credentials + sessions before onboarding)
 - `--reset-scope <config|config+creds+sessions|full>` (default `config+creds+sessions`; use `full` to also remove workspace)
 - `--non-interactive`
 - `--mode <local|remote>`
--- a/docs/cli/onboard.md
+++ b/docs/cli/onboard.md
@ -1,5 +1,5 @@
 ---
-summary: "CLI reference for `openclaw onboard` (interactive setup wizard)"
+summary: "CLI reference for `openclaw onboard` (interactive onboarding)"
 read_when:
  - You want guided setup for gateway, workspace, auth, channels, and skills
 title: "onboard"
@ -7,11 +7,11 @@ title: "onboard"

 # `openclaw onboard`

-Interactive setup wizard (local or remote Gateway setup).
+Interactive onboarding for local or remote Gateway setup.

 ## Related guides

- CLI onboarding hub: [Setup Wizard (CLI)](/start/wizard)
+- CLI onboarding hub: [Onboarding (CLI)](/start/wizard)
 - Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
 - CLI onboarding reference: [CLI Setup Reference](/start/wizard-cli-reference)
 - CLI automation: [CLI Automation](/start/wizard-cli-automation)
--- a/docs/cli/setup.md
+++ b/docs/cli/setup.md
@ -1,7 +1,7 @@
 ---
 summary: "CLI reference for `openclaw setup` (initialize config + workspace)"
 read_when:
-  - You’re doing first-run setup without the full setup wizard
+  - You’re doing first-run setup without full CLI onboarding
  - You want to set the default workspace path
 title: "setup"
 ---
@ -13,7 +13,7 @@ Initialize `~/.openclaw/openclaw.json` and the agent workspace.
 Related:

 - Getting started: [Getting started](/start/getting-started)
- Wizard: [Onboarding](/start/onboarding)
+- CLI onboarding: [Onboarding (CLI)](/start/wizard)

 ## Examples

@ -22,7 +22,7 @@ openclaw setup
 openclaw setup --workspace ~/.openclaw/workspace
 ```

-To run the wizard via setup:
+To run onboarding via setup:

 ```bash
 openclaw setup --wizard
--- a/docs/concepts/models.md
+++ b/docs/concepts/models.md
@ -34,9 +34,9 @@ Related:
 - Use fallbacks for cost/latency-sensitive tasks and lower-stakes chat.
 - For tool-enabled agents or untrusted inputs, avoid older/weaker model tiers.

-## Setup wizard (recommended)
+## Onboarding (recommended)

-If you don’t want to hand-edit config, run the setup wizard:
+If you don’t want to hand-edit config, run onboarding:

 ```bash
 openclaw onboard
--- a/docs/gateway/authentication.md
+++ b/docs/gateway/authentication.md
@ -49,7 +49,7 @@ openclaw models status
 openclaw doctor
 ```

-If you’d rather not manage env vars yourself, the setup wizard can store
+If you’d rather not manage env vars yourself, onboarding can store
 API keys for daemon use: `openclaw onboard`.

 See [Help](/help) for details on env inheritance (`env.shellEnv`,
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@ -2443,6 +2443,12 @@ See [Plugins](/tools/plugin).
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
+      brave: {
+        driver: "existing-session",
+        attachOnly: true,
+        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+        color: "#FB542B",
+      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
@ -2463,6 +2469,8 @@ See [Plugins](/tools/plugin).
 - In strict mode, use `ssrfPolicy.hostnameAllowlist` and `ssrfPolicy.allowedHostnames` for explicit exceptions.
 - Remote profiles are attach-only (start/stop/reset disabled).
 - `existing-session` profiles are host-only and use Chrome MCP instead of CDP.
+- `existing-session` profiles can set `userDataDir` to target a specific
+  Chromium-based browser profile such as Brave or Edge.
 - Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary.
 - Control service: loopback only (port derived from `gateway.port`, default `18791`).
 - `extraArgs` appends extra launch flags to local Chromium startup (for example
@ -2942,7 +2950,7 @@ Notes:

 ## Wizard

-Metadata written by CLI wizards (`onboard`, `configure`, `doctor`):
+Metadata written by CLI guided setup flows (`onboard`, `configure`, `doctor`):

 ```json5
 {
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@ -38,7 +38,7 @@ See the [full reference](/gateway/configuration-reference) for every available f
 <Tabs>
  <Tab title="Interactive wizard">
    ```bash
-    openclaw onboard       # full setup wizard
+    openclaw onboard       # full onboarding flow
    openclaw configure     # config wizard
    ```
  </Tab>
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@ -155,18 +155,20 @@ normalizes it to the current host-local Chrome MCP attach model:
 Doctor also audits the host-local Chrome MCP path when you use `defaultProfile:
 "user"` or a configured `existing-session` profile:

- checks whether Google Chrome is installed on the same host
+- checks whether Google Chrome is installed on the same host for default
+  auto-connect profiles
 - checks the detected Chrome version and warns when it is below Chrome 144
- reminds you to enable remote debugging in Chrome at
-  `chrome://inspect/#remote-debugging`
+- reminds you to enable remote debugging in the browser inspect page (for
+  example `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
+  or `edge://inspect/#remote-debugging`)

 Doctor cannot enable the Chrome-side setting for you. Host-local Chrome MCP
 still requires:

- Google Chrome 144+ on the gateway/node host
- Chrome running locally
- remote debugging enabled in Chrome
- approving the first attach consent prompt in Chrome
+- a Chromium-based browser 144+ on the gateway/node host
+- the browser running locally
+- remote debugging enabled in that browser
+- approving the first attach consent prompt in the browser

 This check does **not** apply to Docker, sandbox, remote-browser, or other
 headless flows. Those continue to use raw CDP.
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@ -738,7 +738,7 @@ In minimal mode, the Gateway still broadcasts enough for device discovery (`role
 Gateway auth is **required by default**. If no token/password is configured,
 the Gateway refuses WebSocket connections (fail‑closed).

-The setup wizard generates a token by default (even for loopback) so
+Onboarding generates a token by default (even for loopback) so
 local clients must authenticate.

 Set a token so **all** WS clients must authenticate:
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@ -36,7 +36,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
  - [How do I install OpenClaw on a VPS?](#how-do-i-install-openclaw-on-a-vps)
  - [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides)
  - [Can I ask OpenClaw to update itself?](#can-i-ask-openclaw-to-update-itself)
-  - [What does the setup wizard actually do?](#what-does-the-setup-wizard-actually-do)
+  - [What does onboarding actually do?](#what-does-onboarding-actually-do)
  - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this)
  - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key)
  - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work)
@ -317,7 +317,7 @@ Install docs: [Install](/install), [Installer flags](/install/installer), [Updat

 ### What's the recommended way to install and set up OpenClaw

-The repo recommends running from source and using the setup wizard:
+The repo recommends running from source and using onboarding:

 ```bash
 curl -fsSL https://openclaw.ai/install.sh | bash
@ -627,7 +627,7 @@ More detail: [Install](/install) and [Installer flags](/install/installer).

 ### How do I install OpenClaw on Linux

-Short answer: follow the Linux guide, then run the setup wizard.
+Short answer: follow the Linux guide, then run onboarding.

 - Linux quick path + service install: [Linux](/platforms/linux).
 - Full walkthrough: [Getting Started](/start/getting-started).
@ -685,7 +685,7 @@ openclaw gateway restart

 Docs: [Update](/cli/update), [Updating](/install/updating).

-### What does the setup wizard actually do
+### What does onboarding actually do

 `openclaw onboard` is the recommended setup path. In **local mode** it walks you through:

@ -723,7 +723,7 @@ If you want the clearest and safest supported path for production, use an Anthro

 ### How does Anthropic setuptoken auth work

-`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. Choose **Anthropic token (paste setup-token)** in the wizard or paste it with `openclaw models auth paste-token --provider anthropic`. The token is stored as an auth profile for the **anthropic** provider and used like an API key (no auto-refresh). More detail: [OAuth](/concepts/oauth).
+`claude setup-token` generates a **token string** via the Claude Code CLI (it is not available in the web console). You can run it on **any machine**. Choose **Anthropic token (paste setup-token)** in onboarding or paste it with `openclaw models auth paste-token --provider anthropic`. The token is stored as an auth profile for the **anthropic** provider and used like an API key (no auto-refresh). More detail: [OAuth](/concepts/oauth).

 ### Where do I find an Anthropic setuptoken

@ -733,7 +733,7 @@ It is **not** in the Anthropic Console. The setup-token is generated by the **Cl
 claude setup-token
 ```

-Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).
+Copy the token it prints, then choose **Anthropic token (paste setup-token)** in onboarding. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).

 ### Do you support Claude subscription auth (Claude Pro or Max)

@ -767,15 +767,15 @@ Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**.

 ### How does Codex auth work

-OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Wizard](/start/wizard).
+OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).

 ### Do you support OpenAI subscription auth Codex OAuth

 Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
 OpenAI explicitly allows subscription OAuth usage in external tools/workflows
-like OpenClaw. The setup wizard can run the OAuth flow for you.
+like OpenClaw. Onboarding can run the OAuth flow for you.

-See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard).
+See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).

 ### How do I set up Gemini CLI OAuth

@ -844,7 +844,7 @@ without WhatsApp/Telegram.

 `channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username.

-The setup wizard accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.
+Onboarding accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.

 Safer (no third-party bot):

@ -1909,7 +1909,7 @@ openclaw onboard --install-daemon

 Notes:

- The setup wizard also offers **Reset** if it sees an existing config. See [Wizard](/start/wizard).
+- Onboarding also offers **Reset** if it sees an existing config. See [Onboarding (CLI)](/start/wizard).
 - If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-<profile>`).
 - Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).

--- a/docs/index.md
+++ b/docs/index.md
@ -33,7 +33,7 @@ title: "OpenClaw"
  <Card title="Get Started" href="/start/getting-started" icon="rocket">
    Install OpenClaw and bring up the Gateway in minutes.
  </Card>
-  <Card title="Run the Wizard" href="/start/wizard" icon="sparkles">
+  <Card title="Run Onboarding" href="/start/wizard" icon="sparkles">
    Guided setup with `openclaw onboard` and pairing flows.
  </Card>
  <Card title="Open the Control UI" href="/web/control-ui" icon="layout-dashboard">
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@ -51,7 +51,7 @@ From repo root:
 This script:

 - builds the gateway image locally (or pulls a remote image if `OPENCLAW_IMAGE` is set)
- runs the setup wizard
+- runs onboarding
 - prints optional provider setup hints
 - starts the gateway via Docker Compose
 - generates a gateway token and writes it to `.env`
--- a/docs/install/index.md
+++ b/docs/install/index.md
@ -33,7 +33,7 @@ For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possibl

 <AccordionGroup>
  <Accordion title="Installer script" icon="rocket" defaultOpen>
-    Downloads the CLI, installs it globally via npm, and launches the setup wizard.
+    Downloads the CLI, installs it globally via npm, and launches onboarding.

    <Tabs>
      <Tab title="macOS / Linux / WSL2">
--- a/docs/install/northflank.mdx
+++ b/docs/install/northflank.mdx
@ -21,7 +21,7 @@ and you configure everything via the `/setup` web wizard.
 ## What you get

 - Hosted OpenClaw Gateway + Control UI
- Web setup wizard at `/setup` (no terminal commands)
+- Web setup at `/setup` (no terminal commands)
 - Persistent storage via Northflank Volume (`/data`) so config/credentials/workspace survive redeploys

 ## Setup flow
@ -32,7 +32,7 @@ and you configure everything via the `/setup` web wizard.
 4. Click **Run setup**.
 5. Open the Control UI at `https://<your-northflank-domain>/openclaw`

-If Telegram DMs are set to pairing, the setup wizard can approve the pairing code.
+If Telegram DMs are set to pairing, web setup can approve the pairing code.

 ## Getting chat tokens

--- a/docs/install/railway.mdx
+++ b/docs/install/railway.mdx
@ -29,13 +29,13 @@ Railway will either:

 Then open:

- `https://<your-railway-domain>/setup` — setup wizard (password protected)
+- `https://<your-railway-domain>/setup` — web setup (password protected)
 - `https://<your-railway-domain>/openclaw` — Control UI

 ## What you get

 - Hosted OpenClaw Gateway + Control UI
- Web setup wizard at `/setup` (no terminal commands)
+- Web setup at `/setup` (no terminal commands)
 - Persistent storage via Railway Volume (`/data`) so config/credentials/workspace survive redeploys
 - Backup export at `/setup/export` to migrate off Railway later

@ -70,7 +70,7 @@ Set these variables on the service:
 3. (Optional) Add Telegram/Discord/Slack tokens.
 4. Click **Run setup**.

-If Telegram DMs are set to pairing, the setup wizard can approve the pairing code.
+If Telegram DMs are set to pairing, web setup can approve the pairing code.

 ## Getting chat tokens

--- a/docs/install/render.mdx
+++ b/docs/install/render.mdx
@ -73,7 +73,7 @@ The Blueprint defaults to `starter`. To use free tier, change `plan: free` in yo

 ## After deployment

-### Complete the setup wizard
+### Complete web setup

 1. Navigate to `https://<your-service>.onrender.com/setup`
 2. Enter your `SETUP_PASSWORD`
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@ -22,7 +22,7 @@ curl -fsSL https://openclaw.ai/install.sh | bash

 Notes:

- Add `--no-onboard` if you don’t want the setup wizard to run again.
+- Add `--no-onboard` if you don’t want onboarding to run again.
 - For **source installs**, use:

  ```bash
--- a/docs/platforms/raspberry-pi.md
+++ b/docs/platforms/raspberry-pi.md
@ -321,7 +321,7 @@ Since the Pi is just the Gateway (models run in the cloud), use API-based models

 ## Auto-Start on Boot

-The setup wizard sets this up, but to verify:
+Onboarding sets this up, but to verify:

 ```bash
 # Check service is enabled
--- a/docs/plugins/voice-call.md
+++ b/docs/plugins/voice-call.md
@ -204,7 +204,7 @@ Example with a stable public host:

 ## TTS for calls

-Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for
+Voice Call uses the core `messages.tts` configuration for
 streaming speech on calls. You can override it under the plugin config with the
 **same shape** — it deep‑merges with `messages.tts`.

@ -222,7 +222,7 @@ streaming speech on calls. You can override it under the plugin config with the

 Notes:

- **Edge TTS is ignored for voice calls** (telephony audio needs PCM; Edge output is unreliable).
+- **Microsoft speech is ignored for voice calls** (telephony audio needs PCM; the current Microsoft transport does not expose telephony PCM output).
 - Core TTS is used when Twilio media streaming is enabled; otherwise calls fall back to provider native voices.

 ### More examples
--- a/docs/providers/ollama.md
+++ b/docs/providers/ollama.md
@ -16,15 +16,15 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo

 ## Quick start

-### Onboarding wizard (recommended)
+### Onboarding (recommended)

-The fastest way to set up Ollama is through the setup wizard:
+The fastest way to set up Ollama is through onboarding:

 ```bash
 openclaw onboard
 ```

-Select **Ollama** from the provider list. The wizard will:
+Select **Ollama** from the provider list. Onboarding will:

 1. Ask for the Ollama base URL where your instance can be reached (default `http://127.0.0.1:11434`).
 2. Let you choose **Cloud + Local** (cloud models and local models) or **Local** (local models only).
--- a/docs/reference/wizard.md
+++ b/docs/reference/wizard.md
@ -1,24 +1,24 @@
 ---
-summary: "Full reference for the CLI setup wizard: every step, flag, and config field"
+summary: "Full reference for CLI onboarding: every step, flag, and config field"
 read_when:
-  - Looking up a specific wizard step or flag
+  - Looking up a specific onboarding step or flag
  - Automating onboarding with non-interactive mode
-  - Debugging wizard behavior
-title: "Setup Wizard Reference"
-sidebarTitle: "Wizard Reference"
+  - Debugging onboarding behavior
+title: "Onboarding Reference"
+sidebarTitle: "Onboarding Reference"
 ---

-# Setup Wizard Reference
+# Onboarding Reference

-This is the full reference for the `openclaw onboard` CLI wizard.
-For a high-level overview, see [Setup Wizard](/start/wizard).
+This is the full reference for `openclaw onboard`.
+For a high-level overview, see [Onboarding (CLI)](/start/wizard).

 ## Flow details (local mode)

 <Steps>
  <Step title="Existing config detection">
    - If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.
-    - Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**
+    - Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset**
      (or pass `--reset`).
    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full`
      to also remove workspace.
@ -31,9 +31,9 @@ For a high-level overview, see [Setup Wizard](/start/wizard).
  </Step>
  <Step title="Model/Auth">
    - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
-    - **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
+    - **Anthropic OAuth (Claude Code CLI)**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
    - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
-    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
+    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it.
    - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles.
@ -55,7 +55,7 @@ For a high-level overview, see [Setup Wizard](/start/wizard).
    - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
    - **Skip**: no auth configured yet.
    - Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
-    - Wizard runs a model check and warns if the configured model is unknown or missing auth.
+    - Onboarding runs a model check and warns if the configured model is unknown or missing auth.
    - API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
    - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
    - More detail: [/concepts/oauth](/concepts/oauth)
@ -106,7 +106,7 @@ For a high-level overview, see [Setup Wizard](/start/wizard).
    - macOS: LaunchAgent
      - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
    - Linux (and Windows via WSL2): systemd user unit
-      - Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+      - Onboarding attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
    - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
    - If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist resolved plaintext token values into supervisor service environment metadata.
@ -128,8 +128,8 @@ For a high-level overview, see [Setup Wizard](/start/wizard).
 </Steps>

 <Note>
-If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
-If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+If no GUI is detected, onboarding prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If the Control UI assets are missing, onboarding attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
 </Note>

 ## Non-interactive mode
@ -183,12 +183,12 @@ openclaw agents add work \

 ## Gateway wizard RPC

-The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+The Gateway exposes the onboarding flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
 Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.

 ## Signal setup (signal-cli)

-The wizard can install `signal-cli` from GitHub releases:
+Onboarding can install `signal-cli` from GitHub releases:

 - Downloads the appropriate release asset.
 - Stores it under `~/.openclaw/tools/signal-cli/<version>/`.
@ -223,12 +223,12 @@ Typical fields in `~/.openclaw/openclaw.json`:
 WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
 Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.

-Some channels are delivered as plugins. When you pick one during setup, the wizard
+Some channels are delivered as plugins. When you pick one during setup, onboarding
 will prompt to install it (npm or a local path) before it can be configured.

 ## Related docs

- Wizard overview: [Setup Wizard](/start/wizard)
+- Onboarding overview: [Onboarding (CLI)](/start/wizard)
 - macOS app onboarding: [Onboarding](/start/onboarding)
 - Config reference: [Gateway configuration](/gateway/configuration)
 - Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@ -52,13 +52,13 @@ Check your Node version with `node --version` if you are unsure.
    </Note>

  </Step>
-  <Step title="Run the setup wizard">
+  <Step title="Run onboarding">
    ```bash
    openclaw onboard --install-daemon
    ```

-    The wizard configures auth, gateway settings, and optional channels.
-    See [Setup Wizard](/start/wizard) for details.
+    Onboarding configures auth, gateway settings, and optional channels.
+    See [Onboarding (CLI)](/start/wizard) for details.

  </Step>
  <Step title="Check the Gateway">
@ -114,8 +114,8 @@ Full environment variable reference: [Environment vars](/help/environment).
 ## Go deeper

 <Columns>
-  <Card title="Setup Wizard (details)" href="/start/wizard">
-    Full CLI wizard reference and advanced options.
+  <Card title="Onboarding (CLI)" href="/start/wizard">
+    Full CLI onboarding reference and advanced options.
  </Card>
  <Card title="macOS app onboarding" href="/start/onboarding">
    First run flow for the macOS app.
--- a/docs/start/hubs.md
+++ b/docs/start/hubs.md
@ -19,7 +19,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Getting Started](/start/getting-started)
 - [Quick start](/start/quickstart)
 - [Onboarding](/start/onboarding)
- [Wizard](/start/wizard)
+- [Onboarding (CLI)](/start/wizard)
 - [Setup](/start/setup)
 - [Dashboard (local Gateway)](http://127.0.0.1:18789/)
 - [Help](/help)
--- a/docs/start/onboarding-overview.md
+++ b/docs/start/onboarding-overview.md
@ -14,21 +14,21 @@ and how you prefer to configure providers.

 ## Choose your onboarding path

- **CLI wizard** for macOS, Linux, and Windows (via WSL2).
+- **CLI onboarding** for macOS, Linux, and Windows (via WSL2).
 - **macOS app** for a guided first run on Apple silicon or Intel Macs.

-## CLI setup wizard
+## CLI onboarding

-Run the wizard in a terminal:
+Run onboarding in a terminal:

 ```bash
 openclaw onboard
 ```

-Use the CLI wizard when you want full control of the Gateway, workspace,
+Use CLI onboarding when you want full control of the Gateway, workspace,
 channels, and skills. Docs:

- [Setup Wizard (CLI)](/start/wizard)
+- [Onboarding (CLI)](/start/wizard)
 - [`openclaw onboard` command](/cli/onboard)

 ## macOS app onboarding
@ -41,7 +41,7 @@ Use the OpenClaw app when you want a fully guided setup on macOS. Docs:

 If you need an endpoint that is not listed, including hosted providers that
 expose standard OpenAI or Anthropic APIs, choose **Custom Provider** in the
-CLI wizard. You will be asked to:
+CLI onboarding. You will be asked to:

 - Pick OpenAI-compatible, Anthropic-compatible, or **Unknown** (auto-detect).
 - Enter a base URL and API key (if required by the provider).
--- a/docs/start/quickstart.md
+++ b/docs/start/quickstart.md
@ -16,7 +16,7 @@ Quick start is now part of [Getting Started](/start/getting-started).
  <Card title="Getting Started" href="/start/getting-started">
    Install OpenClaw and run your first chat in minutes.
  </Card>
-  <Card title="Onboarding Wizard" href="/start/wizard">
-    Full CLI wizard reference and advanced options.
+  <Card title="Onboarding (CLI)" href="/start/wizard">
+    Full CLI onboarding reference and advanced options.
  </Card>
 </Columns>
--- a/docs/start/setup.md
+++ b/docs/start/setup.md
@ -10,7 +10,7 @@ title: "Setup"

 <Note>
 If you are setting up for the first time, start with [Getting Started](/start/getting-started).
-For wizard details, see [Onboarding Wizard](/start/wizard).
+For onboarding details, see [Onboarding (CLI)](/start/wizard).
 </Note>

 Last updated: 2026-01-01
--- a/docs/start/wizard-cli-automation.md
+++ b/docs/start/wizard-cli-automation.md
@ -33,7 +33,7 @@ openclaw onboard --non-interactive \
 Add `--json` for a machine-readable summary.

 Use `--secret-input-mode ref` to store env-backed refs in auth profiles instead of plaintext values.
-Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the setup wizard flow.
+Interactive selection between env refs and configured provider refs (`file` or `exec`) is available in the onboarding flow.

 In non-interactive `ref` mode, provider env vars must be set in the process environment.
 Passing inline key flags without the matching env var now fails fast.
@ -210,6 +210,6 @@ Notes:

 ## Related docs

- Onboarding hub: [Setup Wizard (CLI)](/start/wizard)
+- Onboarding hub: [Onboarding (CLI)](/start/wizard)
 - Full reference: [CLI Setup Reference](/start/wizard-cli-reference)
 - Command reference: [`openclaw onboard`](/cli/onboard)
--- a/docs/start/wizard-cli-reference.md
+++ b/docs/start/wizard-cli-reference.md
@ -10,7 +10,7 @@ sidebarTitle: "CLI reference"
 # CLI Setup Reference

 This page is the full reference for `openclaw onboard`.
-For the short guide, see [Setup Wizard (CLI)](/start/wizard).
+For the short guide, see [Onboarding (CLI)](/start/wizard).

 ## What the wizard does

@ -294,6 +294,6 @@ Signal setup behavior:

 ## Related docs

- Onboarding hub: [Setup Wizard (CLI)](/start/wizard)
+- Onboarding hub: [Onboarding (CLI)](/start/wizard)
 - Automation and scripts: [CLI Automation](/start/wizard-cli-automation)
 - Command reference: [`openclaw onboard`](/cli/onboard)
--- a/docs/start/wizard.md
+++ b/docs/start/wizard.md
@ -1,15 +1,15 @@
 ---
-summary: "CLI setup wizard: guided setup for gateway, workspace, channels, and skills"
+summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
 read_when:
-  - Running or configuring the setup wizard
+  - Running or configuring CLI onboarding
  - Setting up a new machine
-title: "Setup Wizard (CLI)"
+title: "Onboarding (CLI)"
 sidebarTitle: "Onboarding: CLI"
 ---

-# Setup Wizard (CLI)
+# Onboarding (CLI)

-The setup wizard is the **recommended** way to set up OpenClaw on macOS,
+CLI onboarding is the **recommended** way to set up OpenClaw on macOS,
 Linux, or Windows (via WSL2; strongly recommended).
 It configures a local Gateway or a remote Gateway connection, plus channels, skills,
 and workspace defaults in one guided flow.
@ -35,7 +35,7 @@ openclaw agents add <name>
 </Note>

 <Tip>
-The setup wizard includes a web search step where you can pick a provider
+CLI onboarding includes a web search step where you can pick a provider
 (Perplexity, Brave, Gemini, Grok, or Kimi) and paste your API key so the agent
 can use `web_search`. You can also configure this later with
 `openclaw configure --section web`. Docs: [Web tools](/tools/web).
@ -43,7 +43,7 @@ can use `web_search`. You can also configure this later with

 ## QuickStart vs Advanced

-The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
+Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).

 <Tabs>
  <Tab title="QuickStart (defaults)">
@ -61,7 +61,7 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
  </Tab>
 </Tabs>

-## What the wizard configures
+## What onboarding configures

 **Local mode (default)** walks you through these steps:

@ -84,9 +84,9 @@ The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).
 7. **Skills** — Installs recommended skills and optional dependencies.

 <Note>
-Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
+Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
 CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
-If the config is invalid or contains legacy keys, the wizard asks you to run `openclaw doctor` first.
+If the config is invalid or contains legacy keys, onboarding asks you to run `openclaw doctor` first.
 </Note>

 **Remote mode** only configures the local client to connect to a Gateway elsewhere.
@ -95,7 +95,7 @@ It does **not** install or change anything on the remote host.
 ## Add another agent

 Use `openclaw agents add <name>` to create a separate agent with its own workspace,
-sessions, and auth profiles. Running without `--workspace` launches the wizard.
+sessions, and auth profiles. Running without `--workspace` launches onboarding.

 What it sets:

@ -106,7 +106,7 @@ What it sets:
 Notes:

 - Default workspaces follow `~/.openclaw/workspace-<agentId>`.
- Add `bindings` to route inbound messages (the wizard can do this).
+- Add `bindings` to route inbound messages (onboarding can do this).
 - Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.

 ## Full reference
@ -115,7 +115,7 @@ For detailed step-by-step breakdowns and config outputs, see
 [CLI Setup Reference](/start/wizard-cli-reference).
 For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
 For the deeper technical reference, including RPC details, see
-[Wizard Reference](/reference/wizard).
+[Onboarding Reference](/reference/wizard).

 ## Related docs

--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@ -88,6 +88,12 @@ Browser settings live in `~/.openclaw/openclaw.json`.
        attachOnly: true,
        color: "#00AA00",
      },
+      brave: {
+        driver: "existing-session",
+        attachOnly: true,
+        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+        color: "#FB542B",
+      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
@ -114,6 +120,8 @@ Notes:
 - Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.
 - `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do
  not set `cdpUrl` for that driver.
+- Set `browser.profiles.<name>.userDataDir` when an existing-session profile
+  should attach to a non-default Chromium user profile such as Brave or Edge.

 ## Use Brave (or another Chromium-based browser)

@ -289,11 +297,11 @@ Defaults:

 All control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.

-## Chrome existing-session via MCP
+## Existing-session via Chrome DevTools MCP

-OpenClaw can also attach to a running Chrome profile through the official
-Chrome DevTools MCP server. This reuses the tabs and login state already open in
-that Chrome profile.
+OpenClaw can also attach to a running Chromium-based browser profile through the
+official Chrome DevTools MCP server. This reuses the tabs and login state
+already open in that browser profile.

 Official background and setup references:

@ -305,13 +313,41 @@ Built-in profile:
 - `user`

 Optional: create your own custom existing-session profile if you want a
-different name or color.
+different name, color, or browser data directory.

-Then in Chrome:
+Default behavior:

-1. Open `chrome://inspect/#remote-debugging`
-2. Enable remote debugging
-3. Keep Chrome running and approve the connection prompt when OpenClaw attaches
+- The built-in `user` profile uses Chrome MCP auto-connect, which targets the
+  default local Google Chrome profile.
+
+Use `userDataDir` for Brave, Edge, Chromium, or a non-default Chrome profile:
+
+```json5
+{
+  browser: {
+    profiles: {
+      brave: {
+        driver: "existing-session",
+        attachOnly: true,
+        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
+        color: "#FB542B",
+      },
+    },
+  },
+}
+```
+
+Then in the matching browser:
+
+1. Open that browser's inspect page for remote debugging.
+2. Enable remote debugging.
+3. Keep the browser running and approve the connection prompt when OpenClaw attaches.
+
+Common inspect pages:
+
+- Chrome: `chrome://inspect/#remote-debugging`
+- Brave: `brave://inspect/#remote-debugging`
+- Edge: `edge://inspect/#remote-debugging`

 Live attach smoke test:

@ -327,17 +363,17 @@ What success looks like:
 - `status` shows `driver: existing-session`
 - `status` shows `transport: chrome-mcp`
 - `status` shows `running: true`
- `tabs` lists your already-open Chrome tabs
+- `tabs` lists your already-open browser tabs
 - `snapshot` returns refs from the selected live tab

 What to check if attach does not work:

- Chrome is version `144+`
- remote debugging is enabled at `chrome://inspect/#remote-debugging`
- Chrome showed and you accepted the attach consent prompt
+- the target Chromium-based browser is version `144+`
+- remote debugging is enabled in that browser's inspect page
+- the browser showed and you accepted the attach consent prompt
 - `openclaw doctor` migrates old extension-based browser config and checks that
-  Chrome is installed locally with a compatible version, but it cannot enable
-  Chrome-side remote debugging for you
+  Chrome is installed locally for default auto-connect profiles, but it cannot
+  enable browser-side remote debugging for you

 Agent use:

@ -351,10 +387,11 @@ Notes:

 - This path is higher-risk than the isolated `openclaw` profile because it can
  act inside your signed-in browser session.
- OpenClaw does not launch Chrome for this driver; it attaches to an existing
-  session only.
- OpenClaw uses the official Chrome DevTools MCP `--autoConnect` flow here, not
-  the legacy default-profile remote debugging port workflow.
+- OpenClaw does not launch the browser for this driver; it attaches to an
+  existing session only.
+- OpenClaw uses the official Chrome DevTools MCP `--autoConnect` flow here. If
+  `userDataDir` is set, OpenClaw passes it through to target that explicit
+  Chromium user data directory.
 - Existing-session screenshots support page captures and `--ref` element
  captures from snapshots, but not CSS `--element` selectors.
 - Existing-session `wait --url` supports exact, substring, and glob patterns
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@ -97,6 +97,76 @@ The important design boundary:
 That split lets OpenClaw validate config, explain missing/disabled plugins, and
 build UI/schema hints before the full runtime is active.

+## Capability ownership model
+
+OpenClaw treats a native plugin as the ownership boundary for a **company** or a
+**feature**, not as a grab bag of unrelated integrations.
+
+That means:
+
+- a company plugin should usually own all of that company's OpenClaw-facing
+  surfaces
+- a feature plugin should usually own the full feature surface it introduces
+- channels should consume shared core capabilities instead of re-implementing
+  provider behavior ad hoc
+
+Examples:
+
+- the bundled `openai` plugin owns OpenAI model-provider behavior and OpenAI
+  speech behavior
+- the bundled `elevenlabs` plugin owns ElevenLabs speech behavior
+- the bundled `microsoft` plugin owns Microsoft speech behavior
+- the `voice-call` plugin is a feature plugin: it owns call transport, tools,
+  CLI, routes, and runtime, but it consumes core TTS/STT capability instead of
+  inventing a second speech stack
+
+The intended end state is:
+
+- OpenAI lives in one plugin even if it spans text models, speech, images, and
+  future video
+- another vendor can do the same for its own surface area
+- channels do not care which vendor plugin owns the provider; they consume the
+  shared capability contract exposed by core
+
+This is the key distinction:
+
+- **plugin** = ownership boundary
+- **capability** = core contract that multiple plugins can implement or consume
+
+So if OpenClaw adds a new domain such as video, the first question is not
+"which provider should hardcode video handling?" The first question is "what is
+the core video capability contract?" Once that contract exists, vendor plugins
+can register against it and channel/feature plugins can consume it.
+
+If the capability does not exist yet, the right move is usually:
+
+1. define the missing capability in core
+2. expose it through the plugin API/runtime in a typed way
+3. wire channels/features against that capability
+4. let vendor plugins register implementations
+
+This keeps ownership explicit while avoiding core behavior that depends on a
+single vendor or a one-off plugin-specific code path.
+
+### Capability layering
+
+Use this mental model when deciding where code belongs:
+
+- **core capability layer**: shared orchestration, policy, fallback, config
+  merge rules, delivery semantics, and typed contracts
+- **vendor plugin layer**: vendor-specific APIs, auth, model catalogs, speech
+  synthesis, image generation, future video backends, usage endpoints
+- **channel/feature plugin layer**: Slack/Discord/voice-call/etc. integration
+  that consumes core capabilities and presents them on a surface
+
+For example, TTS follows this shape:
+
+- core owns reply-time TTS policy, fallback order, prefs, and channel delivery
+- `openai`, `elevenlabs`, and `microsoft` own synthesis implementations
+- `voice-call` consumes the telephony TTS runtime helper
+
+That same pattern should be preferred for future capabilities.
+
 ## Compatible bundles

 OpenClaw also recognizes two compatible external bundle layouts:
@ -193,6 +263,8 @@ Important trust note:
 - Model Studio provider catalog — bundled as `modelstudio` (enabled by default)
 - Moonshot provider runtime — bundled as `moonshot` (enabled by default)
 - NVIDIA provider catalog — bundled as `nvidia` (enabled by default)
+- ElevenLabs speech provider — bundled as `elevenlabs` (enabled by default)
+- Microsoft speech provider — bundled as `microsoft` (enabled by default; legacy `edge` input maps here)
 - OpenAI provider runtime — bundled as `openai` (enabled by default; owns both `openai` and `openai-codex`)
 - OpenCode Go provider capabilities — bundled as `opencode-go` (enabled by default)
 - OpenCode Zen provider capabilities — bundled as `opencode` (enabled by default)
@ -218,6 +290,8 @@ Native OpenClaw plugins can register:
 - Gateway HTTP routes
 - Agent tools
 - CLI commands
+- Speech providers
+- Web search providers
 - Background services
 - Context engines
 - Provider auth flows and model catalogs
@ -229,6 +303,62 @@ Native OpenClaw plugins can register:
 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
+to reach into random internals and "just make it work." It should register
+against explicit surfaces that OpenClaw understands, validates, and can expose
+consistently across config, onboarding, status, docs, and runtime behavior.
+
+## Contracts and enforcement
+
+The plugin API surface is intentionally typed and centralized in
+`OpenClawPluginApi`. That contract defines the supported registration points and
+the runtime helpers a plugin may rely on.
+
+Why this matters:
+
+- plugin authors get one stable internal standard
+- core can reject duplicate ownership such as two plugins registering the same
+  provider id
+- startup can surface actionable diagnostics for malformed registration
+- contract tests can enforce bundled-plugin ownership and prevent silent drift
+
+There are two layers of enforcement:
+
+1. **runtime registration enforcement**
+   The plugin registry validates registrations as plugins load. Examples:
+   duplicate provider ids, duplicate speech provider ids, and malformed
+   registrations produce plugin diagnostics instead of undefined behavior.
+2. **contract tests**
+   Bundled plugins are captured in contract registries during test runs so
+   OpenClaw can assert ownership explicitly. Today this is used for model
+   providers, web search providers, and bundled registration ownership.
+
+The practical effect is that OpenClaw knows, up front, which plugin owns which
+surface. That lets core and channels compose seamlessly because ownership is
+declared, typed, and testable rather than implicit.
+
+### What belongs in a contract
+
+Good plugin contracts are:
+
+- typed
+- small
+- capability-specific
+- owned by core
+- reusable by multiple plugins
+- consumable by channels/features without vendor knowledge
+
+Bad plugin contracts are:
+
+- vendor-specific policy hidden in core
+- one-off plugin escape hatches that bypass the registry
+- channel code reaching straight into a vendor implementation
+- ad hoc runtime objects that are not part of `OpenClawPluginApi` or
+  `api.runtime`
+
+When in doubt, raise the abstraction level: define the capability first, then
+let plugins plug into it.
+
 ## Provider runtime hooks

 Provider plugins now have two layers:
@ -530,9 +660,36 @@ const result = await api.runtime.tts.textToSpeechTelephony({

 Notes:

- Uses core `messages.tts` configuration (OpenAI or ElevenLabs).
+- Uses core `messages.tts` configuration and provider selection.
 - Returns PCM audio buffer + sample rate. Plugins must resample/encode for providers.
- Edge TTS is not supported for telephony.
+- OpenAI and ElevenLabs support telephony today. Microsoft does not.
+
+Plugins can also register speech providers via `api.registerSpeechProvider(...)`.
+
+```ts
+api.registerSpeechProvider({
+  id: "acme-speech",
+  label: "Acme Speech",
+  isConfigured: ({ config }) => Boolean(config.messages?.tts),
+  synthesize: async (req) => {
+    return {
+      audioBuffer: Buffer.from([]),
+      outputFormat: "mp3",
+      fileExtension: ".mp3",
+      voiceCompatible: false,
+    };
+  },
+});
+```
+
+Notes:
+
+- Keep TTS policy, fallback, and reply delivery in core.
+- Use speech providers for vendor-owned synthesis behavior.
+- Legacy Microsoft `edge` input is normalized to the `microsoft` provider id.
+- The preferred ownership model is company-oriented: one vendor plugin can own
+  text, speech, image, and future media providers as OpenClaw adds those
+  capability contracts.

 For STT/transcription, plugins can call:

@ -842,6 +999,37 @@ instead of the full plugin entry. This keeps startup and setup lighter
 when your main plugin entry also wires tools, hooks, or other runtime-only
 code.

+Optional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
+can opt a channel plugin into the same `setupEntry` path during the gateway's
+pre-listen startup phase, even when the channel is already configured.
+
+Use this only when `setupEntry` fully covers the startup surface that must exist
+before the gateway starts listening. In practice, that means the setup entry
+must register every channel-owned capability that startup depends on, such as:
+
+- channel registration itself
+- any HTTP routes that must be available before the gateway starts listening
+- any gateway methods, tools, or services that must exist during that same window
+
+If your full entry still owns any required startup capability, do not enable
+this flag. Keep the plugin on the default behavior and let OpenClaw load the
+full entry during startup.
+
+Example:
+
+```json
+{
+  "name": "@scope/my-channel",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "setupEntry": "./setup-entry.ts",
+    "startup": {
+      "deferConfiguredChannelFullLoadUntilAfterListen": true
+    }
+  }
+}
+```
+
 ### Channel catalog metadata

 Channel plugins can advertise setup/discovery metadata via `openclaw.channel` and
@ -1079,12 +1267,49 @@ Plugins export either:
 - `on(...)` for typed lifecycle hooks
 - `registerChannel`
 - `registerProvider`
+- `registerSpeechProvider`
+- `registerWebSearchProvider`
 - `registerHttpRoute`
 - `registerCommand`
 - `registerCli`
 - `registerContextEngine`
 - `registerService`

+In practice, `register(api)` is also where a plugin declares **ownership**.
+That ownership should map cleanly to either:
+
+- a vendor surface such as OpenAI, ElevenLabs, or Microsoft
+- a feature surface such as Voice Call
+
+Avoid splitting one vendor's capabilities across unrelated plugins unless there
+is a strong product reason to do so. The default should be one plugin per
+vendor/feature, with core capability contracts separating shared orchestration
+from vendor-specific behavior.
+
+## Adding a new capability
+
+When a plugin needs behavior that does not fit the current API, do not bypass
+the plugin system with a private reach-in. Add the missing capability.
+
+Recommended sequence:
+
+1. define the core contract
+   Decide what shared behavior core should own: policy, fallback, config merge,
+   lifecycle, channel-facing semantics, and runtime helper shape.
+2. add typed plugin registration/runtime surfaces
+   Extend `OpenClawPluginApi` and/or `api.runtime` with the smallest useful
+   typed seam.
+3. wire core + channel/feature consumers
+   Channels and feature plugins should consume the new capability through core,
+   not by importing a vendor implementation directly.
+4. register vendor implementations
+   Vendor plugins then register their backends against the capability.
+5. add contract coverage
+   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.
+
 Context engine plugins can also register a runtime-owned context manager:

 ```ts
@ -1752,6 +1977,7 @@ Publishing contract:

 - Plugin `package.json` must include `openclaw.extensions` with one or more entry files.
 - Optional: `openclaw.setupEntry` may point at a lightweight setup-only entry for disabled or still-unconfigured channel setup.
+- Optional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` may opt a channel plugin into using `setupEntry` during pre-listen gateway startup, but only when that setup entry completely covers the plugin's startup-critical surface.
 - Entry files can be `.js` or `.ts` (jiti loads TS at runtime).
 - `openclaw plugins install <npm-spec>` uses `npm pack`, extracts into `~/.openclaw/extensions/<id>/`, and enables it in config.
 - Config key stability: scoped packages are normalized to the **unscoped** id for `plugins.entries.*`.
--- a/docs/tts.md
+++ b/docs/tts.md
@ -9,26 +9,27 @@ title: "Text-to-Speech"

 # Text-to-speech (TTS)

-OpenClaw can convert outbound replies into audio using ElevenLabs, OpenAI, or Edge TTS.
+OpenClaw can convert outbound replies into audio using ElevenLabs, Microsoft, or OpenAI.
 It works anywhere OpenClaw can send audio; Telegram gets a round voice-note bubble.

 ## Supported services

 - **ElevenLabs** (primary or fallback provider)
+- **Microsoft** (primary or fallback provider; current bundled implementation uses `node-edge-tts`, default when no API keys)
 - **OpenAI** (primary or fallback provider; also used for summaries)
- **Edge TTS** (primary or fallback provider; uses `node-edge-tts`, default when no API keys)

-### Edge TTS notes
+### Microsoft speech notes

-Edge TTS uses Microsoft Edge's online neural TTS service via the `node-edge-tts`
-library. It's a hosted service (not local), uses Microsoft’s endpoints, and does
-not require an API key. `node-edge-tts` exposes speech configuration options and
-output formats, but not all options are supported by the Edge service. citeturn2search0
+The bundled Microsoft speech provider currently uses Microsoft Edge's online
+neural TTS service via the `node-edge-tts` library. It's a hosted service (not
+local), uses Microsoft endpoints, and does not require an API key.
+`node-edge-tts` exposes speech configuration options and output formats, but
+not all options are supported by the service. Legacy config and directive input
+using `edge` still works and is normalized to `microsoft`.

-Because Edge TTS is a public web service without a published SLA or quota, treat it
-as best-effort. If you need guaranteed limits and support, use OpenAI or ElevenLabs.
-Microsoft's Speech REST API documents a 10‑minute audio limit per request; Edge TTS
-does not publish limits, so assume similar or lower limits. citeturn0search3
+Because this path is a public web service without a published SLA or quota,
+treat it as best-effort. If you need guaranteed limits and support, use OpenAI
+or ElevenLabs.

 ## Optional keys

@ -37,8 +38,9 @@ If you want OpenAI or ElevenLabs:
 - `ELEVENLABS_API_KEY` (or `XI_API_KEY`)
 - `OPENAI_API_KEY`

-Edge TTS does **not** require an API key. If no API keys are found, OpenClaw defaults
-to Edge TTS (unless disabled via `messages.tts.edge.enabled=false`).
+Microsoft speech does **not** require an API key. If no API keys are found,
+OpenClaw defaults to Microsoft (unless disabled via
+`messages.tts.microsoft.enabled=false` or `messages.tts.edge.enabled=false`).

 If multiple providers are configured, the selected provider is used first and the others are fallback options.
 Auto-summary uses the configured `summaryModel` (or `agents.defaults.model.primary`),
@ -58,7 +60,7 @@ so that provider must also be authenticated if you enable summaries.
 No. Auto‑TTS is **off** by default. Enable it in config with
 `messages.tts.auto` or per session with `/tts always` (alias: `/tts on`).

-Edge TTS **is** enabled by default once TTS is on, and is used automatically
+Microsoft speech **is** enabled by default once TTS is on, and is used automatically
 when no OpenAI or ElevenLabs API keys are available.

 ## Config
@ -118,15 +120,15 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 }
 ```

-### Edge TTS primary (no API key)
+### Microsoft primary (no API key)

 ```json5
 {
  messages: {
    tts: {
      auto: "always",
-      provider: "edge",
-      edge: {
+      provider: "microsoft",
+      microsoft: {
        enabled: true,
        voice: "en-US-MichelleNeural",
        lang: "en-US",
@ -139,13 +141,13 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 }
 ```

-### Disable Edge TTS
+### Disable Microsoft speech

 ```json5
 {
  messages: {
    tts: {
-      edge: {
+      microsoft: {
        enabled: false,
      },
    },
@ -205,9 +207,10 @@ Then run:
  - `tagged` only sends audio when the reply includes `[[tts]]` tags.
 - `enabled`: legacy toggle (doctor migrates this to `auto`).
 - `mode`: `"final"` (default) or `"all"` (includes tool/block replies).
- `provider`: `"elevenlabs"`, `"openai"`, or `"edge"` (fallback is automatic).
+- `provider`: speech provider id such as `"elevenlabs"`, `"microsoft"`, or `"openai"` (fallback is automatic).
 - If `provider` is **unset**, OpenClaw prefers `openai` (if key), then `elevenlabs` (if key),
-  otherwise `edge`.
+  otherwise `microsoft`.
+- Legacy `provider: "edge"` still works and is normalized to `microsoft`.
 - `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`.
  - Accepts `provider/model` or a configured model alias.
 - `modelOverrides`: allow the model to emit TTS directives (on by default).
@ -227,15 +230,16 @@ Then run:
 - `elevenlabs.applyTextNormalization`: `auto|on|off`
 - `elevenlabs.languageCode`: 2-letter ISO 639-1 (e.g. `en`, `de`)
 - `elevenlabs.seed`: integer `0..4294967295` (best-effort determinism)
- `edge.enabled`: allow Edge TTS usage (default `true`; no API key).
- `edge.voice`: Edge neural voice name (e.g. `en-US-MichelleNeural`).
- `edge.lang`: language code (e.g. `en-US`).
- `edge.outputFormat`: Edge output format (e.g. `audio-24khz-48kbitrate-mono-mp3`).
-  - See Microsoft Speech output formats for valid values; not all formats are supported by Edge.
- `edge.rate` / `edge.pitch` / `edge.volume`: percent strings (e.g. `+10%`, `-5%`).
- `edge.saveSubtitles`: write JSON subtitles alongside the audio file.
- `edge.proxy`: proxy URL for Edge TTS requests.
- `edge.timeoutMs`: request timeout override (ms).
+- `microsoft.enabled`: allow Microsoft speech usage (default `true`; no API key).
+- `microsoft.voice`: Microsoft neural voice name (e.g. `en-US-MichelleNeural`).
+- `microsoft.lang`: language code (e.g. `en-US`).
+- `microsoft.outputFormat`: Microsoft output format (e.g. `audio-24khz-48kbitrate-mono-mp3`).
+  - See Microsoft Speech output formats for valid values; not all formats are supported by the bundled Edge-backed transport.
+- `microsoft.rate` / `microsoft.pitch` / `microsoft.volume`: percent strings (e.g. `+10%`, `-5%`).
+- `microsoft.saveSubtitles`: write JSON subtitles alongside the audio file.
+- `microsoft.proxy`: proxy URL for Microsoft speech requests.
+- `microsoft.timeoutMs`: request timeout override (ms).
+- `edge.*`: legacy alias for the same Microsoft settings.

 ## Model-driven overrides (default on)

@ -260,7 +264,7 @@ Here you go.

 Available directive keys (when enabled):

- `provider` (`openai` | `elevenlabs` | `edge`, requires `allowProvider: true`)
+- `provider` (registered speech provider id, for example `openai`, `elevenlabs`, or `microsoft`; requires `allowProvider: true`)
 - `voice` (OpenAI voice) or `voiceId` (ElevenLabs)
 - `model` (OpenAI TTS model or ElevenLabs model id)
 - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
@ -319,13 +323,12 @@ These override `messages.tts.*` for that host.
  - 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble.
 - **Other channels**: MP3 (`mp3_44100_128` from ElevenLabs, `mp3` from OpenAI).
  - 44.1kHz / 128kbps is the default balance for speech clarity.
- **Edge TTS**: uses `edge.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).
-  - `node-edge-tts` accepts an `outputFormat`, but not all formats are available
-    from the Edge service. citeturn2search0
-  - Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus). citeturn1search0
+- **Microsoft**: uses `microsoft.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).
+  - The bundled transport accepts an `outputFormat`, but not all formats are available from the service.
+  - Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus).
  - Telegram `sendVoice` accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need
    guaranteed Opus voice notes. citeturn1search1
-  - If the configured Edge output format fails, OpenClaw retries with MP3.
+  - If the configured Microsoft output format fails, OpenClaw retries with MP3.

 OpenAI/ElevenLabs formats are fixed; Telegram expects Opus for voice-note UX.

--- a/docs/web/control-ui.md
+++ b/docs/web/control-ui.md
@ -28,7 +28,7 @@ Auth is supplied during the WebSocket handshake via:
 - `connect.params.auth.token`
 - `connect.params.auth.password`
  The dashboard settings panel keeps a token for the current browser tab session and selected gateway URL; passwords are not persisted.
-  The setup wizard generates a gateway token by default, so paste it here on first connect.
+  Onboarding generates a gateway token by default, so paste it here on first connect.

 ## Device pairing (first connection)

--- a/docs/zh-CN/cli/index.md
+++ b/docs/zh-CN/cli/index.md
@ -324,22 +324,22 @@ openclaw [--dev] [--profile <name>] <command>
 选项：

 - `--workspace <dir>`：智能体工作区路径（默认 `~/.openclaw/workspace`）。
- `--wizard`：运行设置向导。
- `--non-interactive`：无提示运行向导。
- `--mode <local|remote>`：向导模式。
+- `--wizard`：运行新手引导。
+- `--non-interactive`：无提示运行新手引导。
+- `--mode <local|remote>`：新手引导模式。
 - `--remote-url <url>`：远程 Gateway 网关 URL。
 - `--remote-token <token>`：远程 Gateway 网关 token。

-只要存在任意向导标志（`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`），就会自动运行向导。
+只要存在任意新手引导标志（`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`），就会自动运行新手引导。

 ### `onboard`

-用于设置 gateway、工作区和 Skills 的交互式向导。
+用于设置 gateway、工作区和 Skills 的交互式新手引导。

 选项：

 - `--workspace <dir>`
- `--reset`（在运行向导前重置配置 + 凭据 + 会话）
+- `--reset`（在运行新手引导前重置配置 + 凭据 + 会话）
 - `--reset-scope <config|config+creds+sessions|full>`（默认 `config+creds+sessions`；使用 `full` 还会删除工作区）
 - `--non-interactive`
 - `--mode <local|remote>`
--- a/docs/zh-CN/cli/onboard.md
+++ b/docs/zh-CN/cli/onboard.md
@ -1,7 +1,7 @@
 ---
 read_when:
  - 你想通过引导式设置来配置 Gateway 网关、工作区、身份验证、渠道和 Skills
-summary: "`openclaw onboard` 的 CLI 参考（交互式设置向导）"
+summary: "`openclaw onboard` 的 CLI 参考（交互式新手引导）"
 title: onboard
 x-i18n:
  generated_at: "2026-03-16T06:21:32Z"
@ -14,11 +14,11 @@ x-i18n:

 # `openclaw onboard`

-交互式设置向导（本地或远程 Gateway 网关设置）。
+交互式新手引导（本地或远程 Gateway 网关设置）。

 ## 相关指南

- CLI 新手引导中心：[设置向导（CLI）](/start/wizard)
+- CLI 新手引导中心：[CLI 新手引导](/start/wizard)
 - 新手引导概览：[新手引导概览](/start/onboarding-overview)
 - CLI 新手引导参考：[CLI 设置参考](/start/wizard-cli-reference)
 - CLI 自动化：[CLI 自动化](/start/wizard-cli-automation)
--- a/docs/zh-CN/cli/setup.md
+++ b/docs/zh-CN/cli/setup.md
@ -1,6 +1,6 @@
 ---
 read_when:
-  - 你正在进行首次运行设置，但不使用完整的设置向导
+  - 你正在进行首次运行设置，但不使用完整的 CLI 新手引导
  - 你想设置默认工作区路径
 summary: "`openclaw setup` 的 CLI 参考（初始化配置 + 工作区）"
 title: setup
@ -20,7 +20,7 @@ x-i18n:
 相关内容：

 - 入门指南：[入门指南](/start/getting-started)
- 向导：[新手引导](/start/onboarding)
+- CLI 新手引导：[CLI 新手引导](/start/wizard)

 ## 示例

@ -29,7 +29,7 @@ openclaw setup
 openclaw setup --workspace ~/.openclaw/workspace
 ```

-通过 setup 运行向导：
+通过 setup 运行新手引导：

 ```bash
 openclaw setup --wizard
--- a/docs/zh-CN/help/faq.md
+++ b/docs/zh-CN/help/faq.md
@ -39,7 +39,7 @@ x-i18n:
  - [如何在 VPS 上安装 OpenClaw？](#how-do-i-install-openclaw-on-a-vps)
  - [云/VPS 安装指南在哪里？](#where-are-the-cloudvps-install-guides)
  - [可以让 OpenClaw 自行更新吗？](#can-i-ask-openclaw-to-update-itself)
-  - [新手引导向导具体做了什么？](#what-does-the-onboarding-wizard-actually-do)
+  - [新手引导具体做了什么？](#新手引导具体做了什么)
  - [运行 OpenClaw 需要 Claude 或 OpenAI 订阅吗？](#do-i-need-a-claude-or-openai-subscription-to-run-this)
  - [能否使用 Claude Max 订阅而不需要 API 密钥？](#can-i-use-claude-max-subscription-without-an-api-key)
  - [Anthropic "setup-token" 认证如何工作？](#how-does-anthropic-setuptoken-auth-work)
@ -310,14 +310,14 @@ openclaw doctor

 ### 安装和设置 OpenClaw 的推荐方式是什么

-仓库推荐从源码运行并使用新手引导向导：
+仓库推荐从源码运行并使用新手引导：

 ```bash
 curl -fsSL https://openclaw.ai/install.sh | bash
 openclaw onboard --install-daemon
 ```

-向导还可以自动构建 UI 资源。新手引导后，通常在端口 **18789** 上运行 Gateway 网关。
+新手引导还可以自动构建 UI 资源。新手引导后，通常在端口 **18789** 上运行 Gateway 网关。

 从源码安装（贡献者/开发者）：

@ -334,7 +334,7 @@ openclaw onboard

 ### 新手引导后如何打开仪表板

-向导现在会在新手引导完成后立即使用带令牌的仪表板 URL 打开浏览器，并在摘要中打印完整链接（带令牌）。保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印的 URL。令牌保持在本地主机上——不会从浏览器获取任何内容。
+新手引导现在会在完成后立即使用带令牌的仪表板 URL 打开浏览器，并在摘要中打印完整链接（带令牌）。保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印的 URL。令牌保持在本地主机上，不会从浏览器获取任何内容。

 ### 如何在本地和远程环境中验证仪表板令牌

@ -562,7 +562,7 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

 ### 如何在 Linux 上安装 OpenClaw

-简短回答：按照 Linux 指南操作，然后运行新手引导向导。
+简短回答：按照 Linux 指南操作，然后运行新手引导。

 - Linux 快速路径 + 服务安装：[Linux](/platforms/linux)。
 - 完整指南：[入门](/start/getting-started)。
@ -614,7 +614,7 @@ openclaw gateway restart

 文档：[更新](/cli/update)、[更新指南](/install/updating)。

-### 新手引导向导具体做了什么
+### 新手引导具体做了什么

 `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它引导你完成：

@ -642,7 +642,7 @@ Claude Pro/Max 订阅**不包含 API 密钥**，因此这是订阅账户的正

 ### Anthropic setup-token 认证如何工作

-`claude setup-token` 通过 Claude Code CLI 生成一个**令牌字符串**（在 Web 控制台中不可用）。你可以在**任何机器**上运行它。在向导中选择 **Anthropic token (paste setup-token)** 或使用 `openclaw models auth paste-token --provider anthropic` 粘贴。令牌作为 **anthropic** 提供商的认证配置文件存储，像 API 密钥一样使用（无自动刷新）。更多详情：[OAuth](/concepts/oauth)。
+`claude setup-token` 通过 Claude Code CLI 生成一个**令牌字符串**（在 Web 控制台中不可用）。你可以在**任何机器**上运行它。在新手引导中选择 **Anthropic token (paste setup-token)** 或使用 `openclaw models auth paste-token --provider anthropic` 粘贴。令牌作为 **anthropic** 提供商的认证配置文件存储，像 API 密钥一样使用（无自动刷新）。更多详情：[OAuth](/concepts/oauth)。

 ### 在哪里获取 Anthropic setup-token

@ -652,7 +652,7 @@ Claude Pro/Max 订阅**不包含 API 密钥**，因此这是订阅账户的正
 claude setup-token
 ```

-复制它打印的令牌，然后在向导中选择 **Anthropic token (paste setup-token)**。如果你想在 Gateway 网关主机上运行，使用 `openclaw models auth setup-token --provider anthropic`。如果你在其他地方运行了 `claude setup-token`，在 Gateway 网关主机上使用 `openclaw models auth paste-token --provider anthropic` 粘贴。参阅 [Anthropic](/providers/anthropic)。
+复制它打印的令牌，然后在新手引导中选择 **Anthropic token (paste setup-token)**。如果你想在 Gateway 网关主机上运行，使用 `openclaw models auth setup-token --provider anthropic`。如果你在其他地方运行了 `claude setup-token`，在 Gateway 网关主机上使用 `openclaw models auth paste-token --provider anthropic` 粘贴。参阅 [Anthropic](/providers/anthropic)。

 ### 是否支持 Claude 订阅认证（Claude Pro/Max）

@ -673,13 +673,13 @@ claude setup-token

 ### Codex 认证如何工作

-OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code (Codex)**。向导可以运行 OAuth 流程，并在适当时将默认模型设置为 `openai-codex/gpt-5.2`。参阅[模型提供商](/concepts/model-providers)和[向导](/start/wizard)。
+OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code (Codex)**。新手引导可以运行 OAuth 流程，并在适当时将默认模型设置为 `openai-codex/gpt-5.2`。参阅[模型提供商](/concepts/model-providers)和[CLI 新手引导](/start/wizard)。

 ### 是否支持 OpenAI 订阅认证（Codex OAuth）

-是的。OpenClaw 完全支持 **OpenAI Code (Codex) 订阅 OAuth**。新手引导向导可以为你运行 OAuth 流程。
+是的。OpenClaw 完全支持 **OpenAI Code (Codex) 订阅 OAuth**。新手引导可以为你运行 OAuth 流程。

-参阅 [OAuth](/concepts/oauth)、[模型提供商](/concepts/model-providers)和[向导](/start/wizard)。
+参阅 [OAuth](/concepts/oauth)、[模型提供商](/concepts/model-providers)和[CLI 新手引导](/start/wizard)。

 ### 如何设置 Gemini CLI OAuth

@ -1632,7 +1632,7 @@ openclaw onboard --install-daemon

 注意：

- 新手引导向导在看到现有配置时也提供**重置**选项。参阅[向导](/start/wizard)。
+- 新手引导在看到现有配置时也提供**重置**选项。参阅[CLI 新手引导](/start/wizard)。
 - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），重置每个状态目录（默认为 `~/.openclaw-<profile>`）。
 - 开发重置：`openclaw gateway --dev --reset`（仅限开发；清除开发配置 + 凭据 + 会话 + 工作区）。

--- a/docs/zh-CN/index.md
+++ b/docs/zh-CN/index.md
@ -40,7 +40,7 @@ x-i18n:
  <Card title="入门指南" href="/start/getting-started" icon="rocket">
    安装 OpenClaw 并在几分钟内启动 Gateway 网关。
  </Card>
-  <Card title="运行向导" href="/start/wizard" icon="sparkles">
+  <Card title="运行新手引导" href="/start/wizard" icon="sparkles">
    通过 `openclaw onboard` 和配对流程进行引导式设置。
  </Card>
  <Card title="打开控制界面" href="/web/control-ui" icon="layout-dashboard">
--- a/docs/zh-CN/start/getting-started.md
+++ b/docs/zh-CN/start/getting-started.md
@ -60,13 +60,13 @@ x-i18n:
    </Note>

  </Step>
-  <Step title="运行设置向导">
+  <Step title="运行新手引导">
    ```bash
    openclaw onboard --install-daemon
    ```

-    向导会配置认证、Gateway 网关设置和可选渠道。
-    详情请参见 [Setup Wizard](/start/wizard)。
+    新手引导会配置认证、Gateway 网关设置和可选渠道。
+    详情请参见 [CLI 新手引导](/start/wizard)。

  </Step>
  <Step title="检查 Gateway 网关">
@ -122,8 +122,8 @@ x-i18n:
 ## 深入了解

 <Columns>
-  <Card title="设置向导（详情）" href="/start/wizard">
-    完整的 CLI 向导参考和高级选项。
+  <Card title="CLI 新手引导" href="/start/wizard">
+    完整的 CLI 新手引导参考和高级选项。
  </Card>
  <Card title="macOS 应用新手引导" href="/start/onboarding">
    macOS 应用的首次运行流程。
--- a/docs/zh-CN/start/hubs.md
+++ b/docs/zh-CN/start/hubs.md
@ -26,7 +26,7 @@ x-i18n:
 - [入门指南](/start/getting-started)
 - [快速开始](/start/quickstart)
 - [新手引导](/start/onboarding)
- [向导](/start/wizard)
+- [CLI 新手引导](/start/wizard)
 - [安装配置](/start/setup)
 - [仪表盘（本地 Gateway 网关）](http://127.0.0.1:18789/)
 - [帮助](/help)
--- a/docs/zh-CN/start/onboarding-overview.md
+++ b/docs/zh-CN/start/onboarding-overview.md
@ -21,21 +21,21 @@ OpenClaw 支持多种新手引导路径，具体取决于 Gateway 网关运行

 ## 选择你的新手引导路径

- 适用于 macOS、Linux 和 Windows（通过 WSL2）的 **CLI 向导**。
+- 适用于 macOS、Linux 和 Windows（通过 WSL2）的 **CLI 新手引导**。
 - 适用于 Apple silicon 或 Intel Mac 的 **macOS 应用**，提供引导式首次运行体验。

-## CLI 设置向导
+## CLI 新手引导

-在终端中运行向导：
+在终端中运行新手引导：

 ```bash
 openclaw onboard
 ```

 当你希望完全控制 Gateway 网关、工作区、
-渠道和 Skills 时，请使用 CLI 向导。文档：
+渠道和 Skills 时，请使用 CLI 新手引导。文档：

- [设置向导（CLI）](/start/wizard)
+- [CLI 新手引导](/start/wizard)
 - [`openclaw onboard` 命令](/cli/onboard)

 ## macOS 应用新手引导
@ -48,7 +48,7 @@ openclaw onboard

 如果你需要一个未列出的端点，包括那些
 公开标准 OpenAI 或 Anthropic API 的托管提供商，请在
-CLI 向导中选择 **Custom Provider**。系统会要求你：
+在 CLI 新手引导中选择 **Custom Provider**。系统会要求你：

 - 选择兼容 OpenAI、兼容 Anthropic，或 **Unknown**（自动检测）。
 - 输入基础 URL 和 API 密钥（如果提供商需要）。
--- a/docs/zh-CN/start/wizard.md
+++ b/docs/zh-CN/start/wizard.md
@ -1,10 +1,10 @@
 ---
 read_when:
-  - 运行或配置设置向导
+  - 运行或配置 CLI 新手引导
  - 设置一台新机器
 sidebarTitle: "Onboarding: CLI"
-summary: CLI 设置向导：用于 Gateway 网关、工作区、渠道和 Skills 的引导式设置
-title: 设置向导（CLI）
+summary: CLI 新手引导：用于 Gateway 网关、工作区、渠道和 Skills 的引导式设置
+title: CLI 新手引导
 x-i18n:
  generated_at: "2026-03-16T06:28:38Z"
  model: gpt-5.4
@ -14,9 +14,9 @@ x-i18n:
  workflow: 15
 ---

-# 设置向导（CLI）
+# CLI 新手引导

-设置向导是在 macOS、
+CLI 新手引导是在 macOS、
 Linux 或 Windows（通过 WSL2；强烈推荐）上设置 OpenClaw 的**推荐**方式。
 它可在一次引导式流程中配置本地 Gateway 网关或远程 Gateway 网关连接，以及渠道、Skills
 和工作区默认值。
@ -42,7 +42,7 @@ openclaw agents add <name>
 </Note>

 <Tip>
-设置向导包含一个 web search 步骤，你可以选择一个提供商
+CLI 新手引导包含一个 web search 步骤，你可以选择一个提供商
 （Perplexity、Brave、Gemini、Grok 或 Kimi），并粘贴你的 API 密钥，以便智能体
 可以使用 `web_search`。你也可以稍后通过
 `openclaw configure --section web` 进行配置。文档：[Web 工具](/tools/web)。
@ -50,7 +50,7 @@ openclaw agents add <name>

 ## 快速开始与高级模式

-向导开始时会让你选择**快速开始**（默认值）或**高级模式**（完全控制）。
+新手引导开始时会让你选择**快速开始**（默认值）或**高级模式**（完全控制）。

 <Tabs>
  <Tab title="快速开始（默认值）">
@ -68,7 +68,7 @@ openclaw agents add <name>
  </Tab>
 </Tabs>

-## 向导会配置什么
+## 新手引导会配置什么

 **本地模式（默认）**会引导你完成以下步骤：

@ -91,9 +91,9 @@ openclaw agents add <name>
 7. **Skills** —— 安装推荐的 Skills 和可选依赖项。

 <Note>
-重新运行向导**不会**清除任何内容，除非你显式选择 **Reset**（或传入 `--reset`）。
+重新运行新手引导**不会**清除任何内容，除非你显式选择 **Reset**（或传入 `--reset`）。
 CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，请使用 `--reset-scope full`。
-如果配置无效或包含旧版键，向导会先要求你运行 `openclaw doctor`。
+如果配置无效或包含旧版键，新手引导会先要求你运行 `openclaw doctor`。
 </Note>

 **远程模式**只会配置本地客户端以连接到其他地方的 Gateway 网关。
@ -102,7 +102,7 @@ CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，
 ## 添加另一个智能体

 使用 `openclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、
-会话和认证配置文件。不带 `--workspace` 运行会启动向导。
+会话和认证配置文件。不带 `--workspace` 运行会启动新手引导。

 它会设置：

@ -113,7 +113,7 @@ CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，
 说明：

 - 默认工作区遵循 `~/.openclaw/workspace-<agentId>`。
- 添加 `bindings` 以路由入站消息（向导可以完成这项操作）。
+- 添加 `bindings` 以路由入站消息（新手引导可以完成这项操作）。
 - 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。

 ## 完整参考
@ -122,7 +122,7 @@ CLI `--reset` 默认会重置配置、凭证和会话；如需包含工作区，
 [CLI 设置参考](/start/wizard-cli-reference)。
 有关非交互式示例，请参见 [CLI 自动化](/start/wizard-cli-automation)。
 有关更深入的技术参考（包括 RPC 细节），请参见
-[向导参考](/reference/wizard)。
+[新手引导参考](/reference/wizard)。

 ## 相关文档

--- a/extensions/bluebubbles/src/actions.runtime.ts
+++ b/extensions/bluebubbles/src/actions.runtime.ts
@ -0,0 +1,13 @@
+export { sendBlueBubblesAttachment } from "./attachments.js";
+export {
+  addBlueBubblesParticipant,
+  editBlueBubblesMessage,
+  leaveBlueBubblesChat,
+  removeBlueBubblesParticipant,
+  renameBlueBubblesChat,
+  setGroupIconBlueBubbles,
+  unsendBlueBubblesMessage,
+} from "./chat.js";
+export { resolveBlueBubblesMessageId } from "./monitor.js";
+export { sendBlueBubblesReaction } from "./reactions.js";
+export { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
--- a/extensions/bluebubbles/src/actions.ts
+++ b/extensions/bluebubbles/src/actions.ts
@ -12,24 +12,18 @@ import {
  type ChannelMessageActionName,
 } from "openclaw/plugin-sdk/bluebubbles";
 import { resolveBlueBubblesAccount } from "./accounts.js";
-import { sendBlueBubblesAttachment } from "./attachments.js";
-import {
-  editBlueBubblesMessage,
-  unsendBlueBubblesMessage,
-  renameBlueBubblesChat,
-  setGroupIconBlueBubbles,
-  addBlueBubblesParticipant,
-  removeBlueBubblesParticipant,
-  leaveBlueBubblesChat,
-} from "./chat.js";
-import { resolveBlueBubblesMessageId } from "./monitor.js";
 import { getCachedBlueBubblesPrivateApiStatus, isMacOS26OrHigher } from "./probe.js";
-import { sendBlueBubblesReaction } from "./reactions.js";
 import { normalizeSecretInputString } from "./secret-input.js";
-import { resolveChatGuidForTarget, sendMessageBlueBubbles } from "./send.js";
 import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
 import type { BlueBubblesSendTarget } from "./types.js";

+let actionsRuntimePromise: Promise<typeof import("./actions.runtime.js")> | null = null;
+
+function loadBlueBubblesActionsRuntime() {
+  actionsRuntimePromise ??= import("./actions.runtime.js");
+  return actionsRuntimePromise;
+}
+
 const providerId = "bluebubbles";

 function mapTarget(raw: string): BlueBubblesSendTarget {
@ -99,6 +93,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
  supportsAction: ({ action }) => SUPPORTED_ACTIONS.has(action),
  extractToolSend: ({ args }) => extractToolSend(args, "sendMessage"),
  handleAction: async ({ action, params, cfg, accountId, toolContext }) => {
+    const runtime = await loadBlueBubblesActionsRuntime();
    const account = resolveBlueBubblesAccount({
      cfg: cfg,
      accountId: accountId ?? undefined,
@ -147,7 +142,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        throw new Error(`BlueBubbles ${action} requires serverUrl and password.`);
      }

-      const resolved = await resolveChatGuidForTarget({ baseUrl, password, target });
+      const resolved = await runtime.resolveChatGuidForTarget({ baseUrl, password, target });
      if (!resolved) {
        throw new Error(`BlueBubbles ${action} failed: chatGuid not found for target.`);
      }
@ -173,11 +168,13 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        );
      }
      // Resolve short ID (e.g., "1", "2") to full UUID
-      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const messageId = runtime.resolveBlueBubblesMessageId(rawMessageId, {
+        requireKnownShortId: true,
+      });
      const partIndex = readNumberParam(params, "partIndex", { integer: true });
      const resolvedChatGuid = await resolveChatGuid();

-      await sendBlueBubblesReaction({
+      await runtime.sendBlueBubblesReaction({
        chatGuid: resolvedChatGuid,
        messageGuid: messageId,
        emoji,
@ -218,11 +215,13 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        );
      }
      // Resolve short ID (e.g., "1", "2") to full UUID
-      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const messageId = runtime.resolveBlueBubblesMessageId(rawMessageId, {
+        requireKnownShortId: true,
+      });
      const partIndex = readNumberParam(params, "partIndex", { integer: true });
      const backwardsCompatMessage = readStringParam(params, "backwardsCompatMessage");

-      await editBlueBubblesMessage(messageId, newText, {
+      await runtime.editBlueBubblesMessage(messageId, newText, {
        ...opts,
        partIndex: typeof partIndex === "number" ? partIndex : undefined,
        backwardsCompatMessage: backwardsCompatMessage ?? undefined,
@ -242,10 +241,12 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        );
      }
      // Resolve short ID (e.g., "1", "2") to full UUID
-      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const messageId = runtime.resolveBlueBubblesMessageId(rawMessageId, {
+        requireKnownShortId: true,
+      });
      const partIndex = readNumberParam(params, "partIndex", { integer: true });

-      await unsendBlueBubblesMessage(messageId, {
+      await runtime.unsendBlueBubblesMessage(messageId, {
        ...opts,
        partIndex: typeof partIndex === "number" ? partIndex : undefined,
      });
@ -276,10 +277,12 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        );
      }
      // Resolve short ID (e.g., "1", "2") to full UUID
-      const messageId = resolveBlueBubblesMessageId(rawMessageId, { requireKnownShortId: true });
+      const messageId = runtime.resolveBlueBubblesMessageId(rawMessageId, {
+        requireKnownShortId: true,
+      });
      const partIndex = readNumberParam(params, "partIndex", { integer: true });

-      const result = await sendMessageBlueBubbles(to, text, {
+      const result = await runtime.sendMessageBlueBubbles(to, text, {
        ...opts,
        replyToMessageGuid: messageId,
        replyToPartIndex: typeof partIndex === "number" ? partIndex : undefined,
@ -313,7 +316,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        );
      }

-      const result = await sendMessageBlueBubbles(to, text, {
+      const result = await runtime.sendMessageBlueBubbles(to, text, {
        ...opts,
        effectId,
      });
@ -330,7 +333,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        throw new Error("BlueBubbles renameGroup requires displayName or name parameter.");
      }

-      await renameBlueBubblesChat(resolvedChatGuid, displayName, opts);
+      await runtime.renameBlueBubblesChat(resolvedChatGuid, displayName, opts);

      return jsonResult({ ok: true, renamed: resolvedChatGuid, displayName });
    }
@ -355,7 +358,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
      // Decode base64 to buffer
      const buffer = Uint8Array.from(atob(base64Buffer), (c) => c.charCodeAt(0));

-      await setGroupIconBlueBubbles(resolvedChatGuid, buffer, filename, {
+      await runtime.setGroupIconBlueBubbles(resolvedChatGuid, buffer, filename, {
        ...opts,
        contentType: contentType ?? undefined,
      });
@ -372,7 +375,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        throw new Error("BlueBubbles addParticipant requires address or participant parameter.");
      }

-      await addBlueBubblesParticipant(resolvedChatGuid, address, opts);
+      await runtime.addBlueBubblesParticipant(resolvedChatGuid, address, opts);

      return jsonResult({ ok: true, added: address, chatGuid: resolvedChatGuid });
    }
@ -386,7 +389,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        throw new Error("BlueBubbles removeParticipant requires address or participant parameter.");
      }

-      await removeBlueBubblesParticipant(resolvedChatGuid, address, opts);
+      await runtime.removeBlueBubblesParticipant(resolvedChatGuid, address, opts);

      return jsonResult({ ok: true, removed: address, chatGuid: resolvedChatGuid });
    }
@ -396,7 +399,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
      assertPrivateApiEnabled();
      const resolvedChatGuid = await resolveChatGuid();

-      await leaveBlueBubblesChat(resolvedChatGuid, opts);
+      await runtime.leaveBlueBubblesChat(resolvedChatGuid, opts);

      return jsonResult({ ok: true, left: resolvedChatGuid });
    }
@ -427,7 +430,7 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
        throw new Error("BlueBubbles sendAttachment requires buffer (base64) parameter.");
      }

-      const result = await sendBlueBubblesAttachment({
+      const result = await runtime.sendBlueBubblesAttachment({
        to,
        buffer,
        filename,
--- a/extensions/bluebubbles/src/channel.runtime.ts
+++ b/extensions/bluebubbles/src/channel.runtime.ts
@ -0,0 +1,6 @@
+export { sendBlueBubblesMedia } from "./media-send.js";
+export { resolveBlueBubblesMessageId } from "./monitor.js";
+export { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
+export { type BlueBubblesProbe, probeBlueBubbles } from "./probe.js";
+export { sendMessageBlueBubbles } from "./send.js";
+export { blueBubblesSetupWizard } from "./setup-surface.js";
--- a/extensions/bluebubbles/src/channel.ts
+++ b/extensions/bluebubbles/src/channel.ts
@ -25,12 +25,8 @@ import {
  resolveDefaultBlueBubblesAccountId,
 } from "./accounts.js";
 import { bluebubblesMessageActions } from "./actions.js";
+import type { BlueBubblesProbe } from "./channel.runtime.js";
 import { BlueBubblesConfigSchema } from "./config-schema.js";
-import { sendBlueBubblesMedia } from "./media-send.js";
-import { resolveBlueBubblesMessageId } from "./monitor.js";
-import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
-import { probeBlueBubbles, type BlueBubblesProbe } from "./probe.js";
-import { sendMessageBlueBubbles } from "./send.js";
 import { blueBubblesSetupAdapter } from "./setup-core.js";
 import { blueBubblesSetupWizard } from "./setup-surface.js";
 import {
@ -41,6 +37,13 @@ import {
  parseBlueBubblesTarget,
 } from "./targets.js";

+let blueBubblesChannelRuntimePromise: Promise<typeof import("./channel.runtime.js")> | null = null;
+
+function loadBlueBubblesChannelRuntime() {
+  blueBubblesChannelRuntimePromise ??= import("./channel.runtime.js");
+  return blueBubblesChannelRuntimePromise;
+}
+
 const meta = {
  id: "bluebubbles",
  label: "BlueBubbles",
@ -221,7 +224,9 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
    idLabel: "bluebubblesSenderId",
    normalizeAllowEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
    notifyApproval: async ({ cfg, id }) => {
-      await sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
+      await (
+        await loadBlueBubblesChannelRuntime()
+      ).sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
        cfg: cfg,
      });
    },
@ -240,12 +245,13 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
      return { ok: true, to: trimmed };
    },
    sendText: async ({ cfg, to, text, accountId, replyToId }) => {
+      const runtime = await loadBlueBubblesChannelRuntime();
      const rawReplyToId = typeof replyToId === "string" ? replyToId.trim() : "";
      // Resolve short ID (e.g., "5") to full UUID
      const replyToMessageGuid = rawReplyToId
-        ? resolveBlueBubblesMessageId(rawReplyToId, { requireKnownShortId: true })
+        ? runtime.resolveBlueBubblesMessageId(rawReplyToId, { requireKnownShortId: true })
        : "";
-      const result = await sendMessageBlueBubbles(to, text, {
+      const result = await runtime.sendMessageBlueBubbles(to, text, {
        cfg: cfg,
        accountId: accountId ?? undefined,
        replyToMessageGuid: replyToMessageGuid || undefined,
@ -253,6 +259,7 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
      return { channel: "bluebubbles", ...result };
    },
    sendMedia: async (ctx) => {
+      const runtime = await loadBlueBubblesChannelRuntime();
      const { cfg, to, text, mediaUrl, accountId, replyToId } = ctx;
      const { mediaPath, mediaBuffer, contentType, filename, caption } = ctx as {
        mediaPath?: string;
@ -262,7 +269,7 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
        caption?: string;
      };
      const resolvedCaption = caption ?? text;
-      const result = await sendBlueBubblesMedia({
+      const result = await runtime.sendBlueBubblesMedia({
        cfg: cfg,
        to,
        mediaUrl,
@ -290,7 +297,7 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
    buildChannelSummary: ({ snapshot }) =>
      buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
    probeAccount: async ({ account, timeoutMs }) =>
-      probeBlueBubbles({
+      (await loadBlueBubblesChannelRuntime()).probeBlueBubbles({
        baseUrl: account.baseUrl,
        password: account.config.password ?? null,
        timeoutMs,
@ -315,8 +322,9 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
  },
  gateway: {
    startAccount: async (ctx) => {
+      const runtime = await loadBlueBubblesChannelRuntime();
      const account = ctx.account;
-      const webhookPath = resolveWebhookPathFromConfig(account.config);
+      const webhookPath = runtime.resolveWebhookPathFromConfig(account.config);
      const statusSink = createAccountStatusSink({
        accountId: ctx.accountId,
        setStatus: ctx.setStatus,
@ -325,7 +333,7 @@ export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
        baseUrl: account.baseUrl,
      });
      ctx.log?.info(`[${account.accountId}] starting provider (webhook=${webhookPath})`);
-      return monitorBlueBubblesProvider({
+      return runtime.monitorBlueBubblesProvider({
        account,
        config: ctx.cfg,
        runtime: ctx.runtime,
--- a/extensions/byteplus/index.ts
+++ b/extensions/byteplus/index.ts
@ -1,10 +1,7 @@
 import { emptyPluginConfigSchema, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import {
-  buildBytePlusCodingProvider,
-  buildBytePlusProvider,
-} from "../../src/agents/models-config.providers.static.js";
 import { ensureModelAllowlistEntry } from "../../src/commands/model-allowlist.js";
 import { createProviderApiKeyAuthMethod } from "../../src/plugins/provider-api-key-auth.js";
+import { buildBytePlusCodingProvider, buildBytePlusProvider } from "./provider-catalog.js";

 const PROVIDER_ID = "byteplus";
 const BYTEPLUS_DEFAULT_MODEL_REF = "byteplus-plan/ark-code-latest";
--- a/extensions/byteplus/provider-catalog.ts
+++ b/extensions/byteplus/provider-catalog.ts
@ -0,0 +1,24 @@
+import {
+  buildBytePlusModelDefinition,
+  BYTEPLUS_BASE_URL,
+  BYTEPLUS_CODING_BASE_URL,
+  BYTEPLUS_CODING_MODEL_CATALOG,
+  BYTEPLUS_MODEL_CATALOG,
+} from "../../src/agents/byteplus-models.js";
+import type { ModelProviderConfig } from "../../src/config/types.models.js";
+
+export function buildBytePlusProvider(): ModelProviderConfig {
+  return {
+    baseUrl: BYTEPLUS_BASE_URL,
+    api: "openai-completions",
+    models: BYTEPLUS_MODEL_CATALOG.map(buildBytePlusModelDefinition),
+  };
+}
+
+export function buildBytePlusCodingProvider(): ModelProviderConfig {
+  return {
+    baseUrl: BYTEPLUS_CODING_BASE_URL,
+    api: "openai-completions",
+    models: BYTEPLUS_CODING_MODEL_CATALOG.map(buildBytePlusModelDefinition),
+  };
+}
--- a/extensions/discord/index.ts
+++ b/extensions/discord/index.ts
@ -1,5 +1,5 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { discordPlugin } from "./src/channel.js";
 import { setDiscordRuntime } from "./src/runtime.js";
 import { registerDiscordSubagentHooks } from "./src/subagent-hooks.js";
--- a/extensions/discord/src/accounts.ts
+++ b/extensions/discord/src/accounts.ts
@ -3,10 +3,12 @@ import type {
  DiscordAccountConfig,
  DiscordActionConfig,
 } from "openclaw/plugin-sdk/discord";
-import { createAccountActionGate } from "../../../src/channels/plugins/account-action-gate.js";
-import { createAccountListHelpers } from "../../../src/channels/plugins/account-helpers.js";
-import { resolveAccountEntry } from "../../../src/routing/account-lookup.js";
-import { normalizeAccountId } from "../../../src/routing/session-key.js";
+import {
+  createAccountActionGate,
+  createAccountListHelpers,
+  normalizeAccountId,
+  resolveAccountEntry,
+} from "../../../src/plugin-sdk-internal/accounts.js";
 import { resolveDiscordToken } from "./token.js";

 export type ResolvedDiscordAccount = {
--- a/extensions/discord/src/draft-chunking.ts
+++ b/extensions/discord/src/draft-chunking.ts
@ -1,5 +1,5 @@
 import { resolveTextChunkLimit } from "../../../src/auto-reply/chunk.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
+import { type OpenClawConfig } from "../../../src/config/config.js";
 import { resolveAccountEntry } from "../../../src/routing/account-lookup.js";
 import { normalizeAccountId } from "../../../src/routing/session-key.js";
 import { DISCORD_TEXT_CHUNK_LIMIT } from "./outbound-adapter.js";
--- a/extensions/discord/src/monitor/native-command.plugin-dispatch.test.ts
+++ b/extensions/discord/src/monitor/native-command.plugin-dispatch.test.ts
@ -4,6 +4,7 @@ import type { NativeCommandSpec } from "../../../../src/auto-reply/commands-regi
 import * as dispatcherModule from "../../../../src/auto-reply/reply/provider-dispatcher.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";
 import { createDiscordNativeCommand } from "./native-command.js";
 import {
  createMockCommandInteraction,
@ -153,6 +154,7 @@ async function expectBoundStatusCommandDispatch(params: {
 describe("Discord native plugin command dispatch", () => {
  beforeEach(() => {
    vi.restoreAllMocks();
+    clearPluginCommands();
    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReset();
    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReturnValue(null);
    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockReset();
@ -162,6 +164,127 @@ describe("Discord native plugin command dispatch", () => {
    });
  });

+  it("executes plugin commands from the real registry through the native Discord command path", async () => {
+    const cfg = createConfig();
+    const commandSpec: NativeCommandSpec = {
+      name: "pair",
+      description: "Pair",
+      acceptsArgs: true,
+    };
+    const command = createDiscordNativeCommand({
+      command: commandSpec,
+      cfg,
+      discordConfig: cfg.channels?.discord ?? {},
+      accountId: "default",
+      sessionPrefix: "discord:slash",
+      ephemeralDefault: true,
+      threadBindings: createNoopThreadBindingManager("default"),
+    });
+    const interaction = createInteraction();
+
+    expect(
+      registerPluginCommand("demo-plugin", {
+        name: "pair",
+        description: "Pair device",
+        acceptsArgs: true,
+        requireAuth: false,
+        handler: async ({ args }) => ({ text: `paired:${args ?? ""}` }),
+      }),
+    ).toEqual({ ok: true });
+
+    const dispatchSpy = vi
+      .spyOn(dispatcherModule, "dispatchReplyWithDispatcher")
+      .mockResolvedValue({} as never);
+
+    await (command as { run: (interaction: unknown) => Promise<void> }).run(
+      Object.assign(interaction, {
+        options: {
+          getString: () => "now",
+          getBoolean: () => null,
+          getFocused: () => "",
+        },
+      }) as unknown,
+    );
+
+    expect(dispatchSpy).not.toHaveBeenCalled();
+    expect(interaction.reply).toHaveBeenCalledWith(
+      expect.objectContaining({ content: "paired:now" }),
+    );
+  });
+
+  it("blocks unauthorized Discord senders before requireAuth:false plugin commands execute", async () => {
+    const cfg = {
+      commands: {
+        allowFrom: {
+          discord: ["user:123456789012345678"],
+        },
+      },
+      channels: {
+        discord: {
+          groupPolicy: "allowlist",
+          guilds: {
+            "345678901234567890": {
+              channels: {
+                "234567890123456789": {
+                  allow: true,
+                  requireMention: false,
+                },
+              },
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+    const commandSpec: NativeCommandSpec = {
+      name: "pair",
+      description: "Pair",
+      acceptsArgs: true,
+    };
+    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",
+      guildId: "345678901234567890",
+      guildName: "Test Guild",
+    });
+    interaction.user.id = "999999999999999999";
+    interaction.options.getString.mockReturnValue("now");
+
+    expect(
+      registerPluginCommand("demo-plugin", {
+        name: "pair",
+        description: "Pair device",
+        acceptsArgs: true,
+        requireAuth: false,
+        handler: async ({ args }) => ({ text: `open:${args ?? ""}` }),
+      }),
+    ).toEqual({ ok: true });
+
+    const executeSpy = vi.spyOn(pluginCommandsModule, "executePluginCommand");
+    const dispatchSpy = vi
+      .spyOn(dispatcherModule, "dispatchReplyWithDispatcher")
+      .mockResolvedValue({} as never);
+
+    await (command as { run: (interaction: unknown) => Promise<void> }).run(interaction as unknown);
+
+    expect(executeSpy).not.toHaveBeenCalled();
+    expect(dispatchSpy).not.toHaveBeenCalled();
+    expect(interaction.reply).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: "You are not authorized to use this command.",
+        ephemeral: true,
+      }),
+    );
+  });
+
  it("executes matched plugin commands directly without invoking the agent dispatcher", async () => {
    const cfg = createConfig();
    const commandSpec: NativeCommandSpec = {
--- a/extensions/discord/src/monitor/native-command.ts
+++ b/extensions/discord/src/monitor/native-command.ts
@ -21,7 +21,6 @@ import {
 } from "../../../../src/acp/persistent-bindings.route.js";
 import { resolveHumanDelayConfig } from "../../../../src/agents/identity.js";
 import { resolveChunkMode, resolveTextChunkLimit } from "../../../../src/auto-reply/chunk.js";
-import { resolveCommandAuthorization } from "../../../../src/auto-reply/command-auth.js";
 import type {
  ChatCommandDefinition,
  CommandArgDefinition,
@ -61,8 +60,10 @@ import { resolveDiscordMaxLinesPerMessage } from "../accounts.js";
 import { chunkDiscordTextWithMode } from "../chunk.js";
 import {
  isDiscordGroupAllowedByPolicy,
+  normalizeDiscordAllowList,
  normalizeDiscordSlug,
  resolveDiscordChannelConfigWithFallback,
+  resolveDiscordAllowListMatch,
  resolveDiscordGuildEntry,
  resolveDiscordMemberAccessState,
  resolveDiscordOwnerAccess,
@ -108,33 +109,26 @@ function resolveDiscordNativeCommandAllowlistAccess(params: {
  if (!commandsAllowFrom || typeof commandsAllowFrom !== "object") {
    return { configured: false, allowed: false } as const;
  }
-  const configured =
-    Array.isArray(commandsAllowFrom.discord) || Array.isArray(commandsAllowFrom["*"]);
-  if (!configured) {
+  const rawAllowList = Array.isArray(commandsAllowFrom.discord)
+    ? commandsAllowFrom.discord
+    : commandsAllowFrom["*"];
+  if (!Array.isArray(rawAllowList)) {
    return { configured: false, allowed: false } as const;
  }
-
-  const from =
-    params.chatType === "direct"
-      ? `discord:${params.sender.id}`
-      : `discord:${params.chatType}:${params.conversationId ?? "unknown"}`;
-  const auth = resolveCommandAuthorization({
-    ctx: {
-      Provider: "discord",
-      Surface: "discord",
-      OriginatingChannel: "discord",
-      AccountId: params.accountId ?? undefined,
-      ChatType: params.chatType,
-      From: from,
-      SenderId: params.sender.id,
-      SenderUsername: params.sender.name,
-      SenderTag: params.sender.tag,
-    },
-    cfg: params.cfg,
-    // We only want explicit commands.allowFrom authorization here.
-    commandAuthorized: false,
+  const allowList = normalizeDiscordAllowList(rawAllowList.map(String), [
+    "discord:",
+    "user:",
+    "pk:",
+  ]);
+  if (!allowList) {
+    return { configured: true, allowed: false } as const;
+  }
+  const match = resolveDiscordAllowListMatch({
+    allowList,
+    candidate: params.sender,
+    allowNameMatching: false,
  });
-  return { configured: true, allowed: auth.isAuthorizedSender } as const;
+  return { configured: true, allowed: match.allowed } as const;
 }

 function buildDiscordCommandOptions(params: {
--- a/extensions/discord/src/monitor/provider.registry.test.ts
+++ b/extensions/discord/src/monitor/provider.registry.test.ts
@ -0,0 +1,366 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../../../../src/config/config.js";
+import { clearPluginCommands, registerPluginCommand } from "../../../../src/plugins/commands.js";
+import type { RuntimeEnv } from "../../../../src/runtime.js";
+
+type NativeCommandSpecMock = {
+  name: string;
+  description: string;
+  acceptsArgs: boolean;
+};
+
+function baseDiscordAccountConfig() {
+  return {
+    commands: { native: true, nativeSkills: false },
+    voice: { enabled: false },
+    agentComponents: { enabled: false },
+    execApprovals: { enabled: false },
+  };
+}
+
+const {
+  clientConstructorOptionsMock,
+  clientFetchUserMock,
+  clientHandleDeployRequestMock,
+  createDiscordAutoPresenceControllerMock,
+  createDiscordMessageHandlerMock,
+  createDiscordNativeCommandMock,
+  createNoopThreadBindingManagerMock,
+  createThreadBindingManagerMock,
+  getAcpSessionStatusMock,
+  listNativeCommandSpecsForConfigMock,
+  listSkillCommandsForAgentsMock,
+  monitorLifecycleMock,
+  reconcileAcpThreadBindingsOnStartupMock,
+  resolveDiscordAccountMock,
+  resolveDiscordAllowlistConfigMock,
+  resolveNativeCommandsEnabledMock,
+  resolveNativeSkillsEnabledMock,
+} = vi.hoisted(() => ({
+  clientConstructorOptionsMock: vi.fn(),
+  clientFetchUserMock: vi.fn(async (_target: string) => ({ id: "bot-1" })),
+  clientHandleDeployRequestMock: vi.fn(async () => undefined),
+  createDiscordAutoPresenceControllerMock: vi.fn(() => ({
+    enabled: false,
+    start: vi.fn(),
+    stop: vi.fn(),
+    refresh: vi.fn(),
+    runNow: vi.fn(),
+  })),
+  createDiscordMessageHandlerMock: vi.fn(() =>
+    Object.assign(
+      vi.fn(async () => undefined),
+      {
+        deactivate: vi.fn(),
+      },
+    ),
+  ),
+  createDiscordNativeCommandMock: vi.fn((params: { command: { name: string } }) => ({
+    name: params.command.name,
+  })),
+  createNoopThreadBindingManagerMock: vi.fn(() => ({ stop: vi.fn() })),
+  createThreadBindingManagerMock: vi.fn(() => ({ stop: vi.fn() })),
+  getAcpSessionStatusMock: vi.fn(
+    async (_params: { cfg: OpenClawConfig; sessionKey: string; signal?: AbortSignal }) => ({
+      state: "idle",
+    }),
+  ),
+  listNativeCommandSpecsForConfigMock: vi.fn<() => NativeCommandSpecMock[]>(() => [
+    { name: "status", description: "Status", acceptsArgs: false },
+  ]),
+  listSkillCommandsForAgentsMock: vi.fn(() => []),
+  monitorLifecycleMock: vi.fn(async (params: { threadBindings: { stop: () => void } }) => {
+    params.threadBindings.stop();
+  }),
+  reconcileAcpThreadBindingsOnStartupMock: vi.fn(() => ({
+    checked: 0,
+    removed: 0,
+    staleSessionKeys: [],
+  })),
+  resolveDiscordAccountMock: vi.fn(() => ({
+    accountId: "default",
+    token: "cfg-token",
+    config: baseDiscordAccountConfig(),
+  })),
+  resolveDiscordAllowlistConfigMock: vi.fn(async () => ({
+    guildEntries: undefined,
+    allowFrom: undefined,
+  })),
+  resolveNativeCommandsEnabledMock: vi.fn(() => true),
+  resolveNativeSkillsEnabledMock: vi.fn(() => false),
+}));
+
+vi.mock("@buape/carbon", () => {
+  class ReadyListener {}
+  class RateLimitError extends Error {
+    status = 429;
+    retryAfter = 0;
+    scope: string | null = null;
+    bucket: string | null = null;
+  }
+  class Client {
+    listeners: unknown[];
+    rest: { put: ReturnType<typeof vi.fn> };
+    constructor(options: unknown, handlers: { listeners?: unknown[] }) {
+      clientConstructorOptionsMock(options);
+      this.listeners = handlers.listeners ?? [];
+      this.rest = { put: vi.fn(async () => undefined) };
+    }
+    async handleDeployRequest() {
+      return await clientHandleDeployRequestMock();
+    }
+    async fetchUser(target: string) {
+      return await clientFetchUserMock(target);
+    }
+    getPlugin() {
+      return undefined;
+    }
+  }
+  return { Client, RateLimitError, ReadyListener };
+});
+
+vi.mock("@buape/carbon/gateway", () => ({
+  GatewayCloseCodes: { DisallowedIntents: 4014 },
+}));
+
+vi.mock("@buape/carbon/voice", () => ({
+  VoicePlugin: class VoicePlugin {},
+}));
+
+vi.mock("../../../../src/acp/control-plane/manager.js", () => ({
+  getAcpSessionManager: () => ({
+    getSessionStatus: getAcpSessionStatusMock,
+  }),
+}));
+
+vi.mock("../../../../src/auto-reply/chunk.js", () => ({
+  resolveTextChunkLimit: () => 2000,
+}));
+
+vi.mock("../../../../src/auto-reply/commands-registry.js", () => ({
+  listNativeCommandSpecsForConfig: listNativeCommandSpecsForConfigMock,
+}));
+
+vi.mock("../../../../src/auto-reply/skill-commands.js", () => ({
+  listSkillCommandsForAgents: listSkillCommandsForAgentsMock,
+}));
+
+vi.mock("../../../../src/config/commands.js", () => ({
+  isNativeCommandsExplicitlyDisabled: () => false,
+  resolveNativeCommandsEnabled: resolveNativeCommandsEnabledMock,
+  resolveNativeSkillsEnabled: resolveNativeSkillsEnabledMock,
+}));
+
+vi.mock("../../../../src/config/config.js", () => ({
+  loadConfig: () => ({}),
+}));
+
+vi.mock("../../../../src/globals.js", () => ({
+  danger: (value: string) => value,
+  isVerbose: () => false,
+  logVerbose: vi.fn(),
+  shouldLogVerbose: () => false,
+  warn: (value: string) => value,
+}));
+
+vi.mock("../../../../src/infra/errors.js", () => ({
+  formatErrorMessage: (error: unknown) => String(error),
+}));
+
+vi.mock("../../../../src/infra/retry-policy.js", () => ({
+  createDiscordRetryRunner: () => async (run: () => Promise<unknown>) => run(),
+}));
+
+vi.mock("../../../../src/logging/subsystem.js", () => ({
+  createSubsystemLogger: () => {
+    const logger = {
+      child: vi.fn(() => logger),
+      info: vi.fn(),
+      error: vi.fn(),
+      warn: vi.fn(),
+      debug: vi.fn(),
+    };
+    return logger;
+  },
+}));
+
+vi.mock("../../../../src/runtime.js", () => ({
+  createNonExitingRuntime: () => ({ log: vi.fn(), error: vi.fn(), exit: vi.fn() }),
+}));
+
+vi.mock("../accounts.js", () => ({
+  resolveDiscordAccount: resolveDiscordAccountMock,
+}));
+
+vi.mock("../probe.js", () => ({
+  fetchDiscordApplicationId: async () => "app-1",
+}));
+
+vi.mock("../token.js", () => ({
+  normalizeDiscordToken: (value?: string) => value,
+}));
+
+vi.mock("../voice/command.js", () => ({
+  createDiscordVoiceCommand: () => ({ name: "voice-command" }),
+}));
+
+vi.mock("./agent-components.js", () => ({
+  createAgentComponentButton: () => ({ id: "btn" }),
+  createAgentSelectMenu: () => ({ id: "menu" }),
+  createDiscordComponentButton: () => ({ id: "btn2" }),
+  createDiscordComponentChannelSelect: () => ({ id: "channel" }),
+  createDiscordComponentMentionableSelect: () => ({ id: "mentionable" }),
+  createDiscordComponentModal: () => ({ id: "modal" }),
+  createDiscordComponentRoleSelect: () => ({ id: "role" }),
+  createDiscordComponentStringSelect: () => ({ id: "string" }),
+  createDiscordComponentUserSelect: () => ({ id: "user" }),
+}));
+
+vi.mock("./auto-presence.js", () => ({
+  createDiscordAutoPresenceController: createDiscordAutoPresenceControllerMock,
+}));
+
+vi.mock("./commands.js", () => ({
+  resolveDiscordSlashCommandConfig: () => ({ ephemeral: false }),
+}));
+
+vi.mock("./exec-approvals.js", () => ({
+  createExecApprovalButton: () => ({ id: "exec-approval" }),
+  DiscordExecApprovalHandler: class DiscordExecApprovalHandler {
+    async start() {
+      return undefined;
+    }
+    async stop() {
+      return undefined;
+    }
+  },
+}));
+
+vi.mock("./gateway-plugin.js", () => ({
+  createDiscordGatewayPlugin: () => ({ id: "gateway-plugin" }),
+}));
+
+vi.mock("./listeners.js", () => ({
+  DiscordMessageListener: class DiscordMessageListener {},
+  DiscordPresenceListener: class DiscordPresenceListener {},
+  DiscordReactionListener: class DiscordReactionListener {},
+  DiscordReactionRemoveListener: class DiscordReactionRemoveListener {},
+  DiscordThreadUpdateListener: class DiscordThreadUpdateListener {},
+  registerDiscordListener: vi.fn(),
+}));
+
+vi.mock("./message-handler.js", () => ({
+  createDiscordMessageHandler: createDiscordMessageHandlerMock,
+}));
+
+vi.mock("./native-command.js", () => ({
+  createDiscordCommandArgFallbackButton: () => ({ id: "arg-fallback" }),
+  createDiscordModelPickerFallbackButton: () => ({ id: "model-fallback-btn" }),
+  createDiscordModelPickerFallbackSelect: () => ({ id: "model-fallback-select" }),
+  createDiscordNativeCommand: createDiscordNativeCommandMock,
+}));
+
+vi.mock("./presence.js", () => ({
+  resolveDiscordPresenceUpdate: () => undefined,
+}));
+
+vi.mock("./provider.allowlist.js", () => ({
+  resolveDiscordAllowlistConfig: resolveDiscordAllowlistConfigMock,
+}));
+
+vi.mock("./provider.lifecycle.js", () => ({
+  runDiscordGatewayLifecycle: monitorLifecycleMock,
+}));
+
+vi.mock("./rest-fetch.js", () => ({
+  resolveDiscordRestFetch: () => async () => undefined,
+}));
+
+vi.mock("./thread-bindings.js", () => ({
+  createNoopThreadBindingManager: createNoopThreadBindingManagerMock,
+  createThreadBindingManager: createThreadBindingManagerMock,
+  reconcileAcpThreadBindingsOnStartup: reconcileAcpThreadBindingsOnStartupMock,
+}));
+
+describe("monitorDiscordProvider real plugin registry", () => {
+  const baseRuntime = (): RuntimeEnv => ({
+    log: vi.fn(),
+    error: vi.fn(),
+    exit: vi.fn(),
+  });
+
+  const baseConfig = (): OpenClawConfig =>
+    ({
+      channels: {
+        discord: {
+          accounts: {
+            default: {},
+          },
+        },
+      },
+    }) as OpenClawConfig;
+
+  beforeEach(() => {
+    clearPluginCommands();
+    clientConstructorOptionsMock.mockClear();
+    clientFetchUserMock.mockClear().mockResolvedValue({ id: "bot-1" });
+    clientHandleDeployRequestMock.mockClear().mockResolvedValue(undefined);
+    createDiscordAutoPresenceControllerMock.mockClear();
+    createDiscordMessageHandlerMock.mockClear();
+    createDiscordNativeCommandMock.mockClear();
+    createNoopThreadBindingManagerMock.mockClear();
+    createThreadBindingManagerMock.mockClear();
+    getAcpSessionStatusMock.mockClear().mockResolvedValue({ state: "idle" });
+    listNativeCommandSpecsForConfigMock
+      .mockClear()
+      .mockReturnValue([{ name: "status", description: "Status", acceptsArgs: false }]);
+    listSkillCommandsForAgentsMock.mockClear().mockReturnValue([]);
+    monitorLifecycleMock.mockClear().mockImplementation(async (params) => {
+      params.threadBindings.stop();
+    });
+    reconcileAcpThreadBindingsOnStartupMock.mockClear().mockReturnValue({
+      checked: 0,
+      removed: 0,
+      staleSessionKeys: [],
+    });
+    resolveDiscordAccountMock.mockClear().mockReturnValue({
+      accountId: "default",
+      token: "cfg-token",
+      config: baseDiscordAccountConfig(),
+    });
+    resolveDiscordAllowlistConfigMock.mockClear().mockResolvedValue({
+      guildEntries: undefined,
+      allowFrom: undefined,
+    });
+    resolveNativeCommandsEnabledMock.mockClear().mockReturnValue(true);
+    resolveNativeSkillsEnabledMock.mockClear().mockReturnValue(false);
+  });
+
+  it("registers plugin commands from the real registry as native Discord commands", async () => {
+    expect(
+      registerPluginCommand("demo-plugin", {
+        name: "pair",
+        description: "Pair device",
+        acceptsArgs: true,
+        requireAuth: false,
+        handler: async ({ args }) => ({ text: `paired:${args ?? ""}` }),
+      }),
+    ).toEqual({ ok: true });
+
+    const { monitorDiscordProvider } = await import("./provider.js");
+
+    await monitorDiscordProvider({
+      config: baseConfig(),
+      runtime: baseRuntime(),
+    });
+
+    const commandNames = (createDiscordNativeCommandMock.mock.calls as Array<unknown[]>)
+      .map((call) => (call[0] as { command?: { name?: string } } | undefined)?.command?.name)
+      .filter((value): value is string => typeof value === "string");
+
+    expect(commandNames).toContain("status");
+    expect(commandNames).toContain("pair");
+    expect(clientHandleDeployRequestMock).toHaveBeenCalledTimes(1);
+    expect(monitorLifecycleMock).toHaveBeenCalledTimes(1);
+  });
+});
--- a/extensions/discord/src/runtime.ts
+++ b/extensions/discord/src/runtime.ts
@ -1,5 +1,5 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";

 const { setRuntime: setDiscordRuntime, getRuntime: getDiscordRuntime } =
  createPluginRuntimeStore<PluginRuntime>("Discord runtime not initialized");
--- a/extensions/discord/src/setup-core.ts
+++ b/extensions/discord/src/setup-core.ts
@ -1,22 +1,23 @@
+import type { DiscordGuildEntry } from "../../../src/config/types.discord.js";
 import {
  applyAccountNameToChannelSection,
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
  migrateBaseNameToDefaultAccount,
-} from "../../../src/channels/plugins/setup-helpers.js";
-import {
+  normalizeAccountId,
  noteChannelLookupFailure,
  noteChannelLookupSummary,
  parseMentionOrPrefixedId,
  patchChannelConfigForAccount,
  setLegacyChannelDmPolicyWithAllowFrom,
  setSetupChannelEnabled,
-} from "../../../src/channels/plugins/setup-wizard-helpers.js";
-import type { ChannelSetupDmPolicy } from "../../../src/channels/plugins/setup-wizard-types.js";
-import type { ChannelSetupWizard } from "../../../src/channels/plugins/setup-wizard.js";
-import type { ChannelSetupAdapter } from "../../../src/channels/plugins/types.adapters.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import type { DiscordGuildEntry } from "../../../src/config/types.discord.js";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../../src/routing/session-key.js";
-import { formatDocsLink } from "../../../src/terminal/links.js";
+  type OpenClawConfig,
+} from "../../../src/plugin-sdk-internal/setup.js";
+import {
+  type ChannelSetupAdapter,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+} from "../../../src/plugin-sdk-internal/setup.js";
 import { inspectDiscordAccount } from "./account-inspect.js";
 import { listDiscordAccountIds, resolveDiscordAccount } from "./accounts.js";

--- a/extensions/discord/src/setup-surface.ts
+++ b/extensions/discord/src/setup-surface.ts
@ -1,19 +1,21 @@
 import {
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
  noteChannelLookupFailure,
  noteChannelLookupSummary,
+  type OpenClawConfig,
  parseMentionOrPrefixedId,
  patchChannelConfigForAccount,
  promptLegacyChannelAllowFrom,
  resolveSetupAccountId,
  setLegacyChannelDmPolicyWithAllowFrom,
  setSetupChannelEnabled,
-} from "../../../src/channels/plugins/setup-wizard-helpers.js";
-import type { ChannelSetupDmPolicy } from "../../../src/channels/plugins/setup-wizard-types.js";
-import type { ChannelSetupWizard } from "../../../src/channels/plugins/setup-wizard.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import { DEFAULT_ACCOUNT_ID } from "../../../src/routing/session-key.js";
-import { formatDocsLink } from "../../../src/terminal/links.js";
-import type { WizardPrompter } from "../../../src/wizard/prompts.js";
+  type WizardPrompter,
+} from "../../../src/plugin-sdk-internal/setup.js";
+import {
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+} from "../../../src/plugin-sdk-internal/setup.js";
 import { inspectDiscordAccount } from "./account-inspect.js";
 import {
  listDiscordAccountIds,
--- a/extensions/discord/src/subagent-hooks.test.ts
+++ b/extensions/discord/src/subagent-hooks.test.ts
@ -35,8 +35,10 @@ const hookMocks = vi.hoisted(() => ({
  unbindThreadBindingsBySessionKey: vi.fn(() => []),
 }));

-vi.mock("openclaw/plugin-sdk/discord", () => ({
+vi.mock("./accounts.js", () => ({
  resolveDiscordAccount: hookMocks.resolveDiscordAccount,
+}));
+vi.mock("./monitor/thread-bindings.js", () => ({
  autoBindSpawnedDiscordSubagent: hookMocks.autoBindSpawnedDiscordSubagent,
  listThreadBindingsBySessionKey: hookMocks.listThreadBindingsBySessionKey,
  unbindThreadBindingsBySessionKey: hookMocks.unbindThreadBindingsBySessionKey,
--- a/extensions/discord/src/subagent-hooks.ts
+++ b/extensions/discord/src/subagent-hooks.ts
@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
 import { resolveDiscordAccount } from "./accounts.js";
 import {
  autoBindSpawnedDiscordSubagent,
--- a/extensions/discord/src/token.ts
+++ b/extensions/discord/src/token.ts
@ -1,4 +1,4 @@
-import type { BaseTokenResolution } from "../../../src/channels/plugins/types.js";
+import type { BaseTokenResolution } from "../../../src/channels/plugins/types.core.js";
 import type { OpenClawConfig } from "../../../src/config/config.js";
 import { normalizeResolvedSecretInputString } from "../../../src/config/types.secrets.js";
 import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../../src/routing/session-key.js";
--- a/extensions/elevenlabs/index.ts
+++ b/extensions/elevenlabs/index.ts
@ -0,0 +1,14 @@
+import { emptyPluginConfigSchema, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { buildElevenLabsSpeechProvider } from "../../src/tts/providers/elevenlabs.js";
+
+const elevenLabsPlugin = {
+  id: "elevenlabs",
+  name: "ElevenLabs Speech",
+  description: "Bundled ElevenLabs speech provider",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    api.registerSpeechProvider(buildElevenLabsSpeechProvider());
+  },
+};
+
+export default elevenLabsPlugin;
--- a/extensions/elevenlabs/openclaw.plugin.json
+++ b/extensions/elevenlabs/openclaw.plugin.json
@ -0,0 +1,8 @@
+{
+  "id": "elevenlabs",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
--- a/extensions/elevenlabs/package.json
+++ b/extensions/elevenlabs/package.json
@ -0,0 +1,12 @@
+{
+  "name": "@openclaw/elevenlabs-speech",
+  "version": "2026.3.14",
+  "private": true,
+  "description": "OpenClaw ElevenLabs speech plugin",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}
--- a/extensions/huggingface/index.ts
+++ b/extensions/huggingface/index.ts
@ -1,10 +1,10 @@
 import { emptyPluginConfigSchema, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { buildHuggingfaceProvider } from "../../src/agents/models-config.providers.discovery.js";
 import {
  applyHuggingfaceConfig,
  HUGGINGFACE_DEFAULT_MODEL_REF,
 } from "../../src/commands/onboard-auth.js";
 import { createProviderApiKeyAuthMethod } from "../../src/plugins/provider-api-key-auth.js";
+import { buildHuggingfaceProvider } from "./provider-catalog.js";

 const PROVIDER_ID = "huggingface";

--- a/extensions/huggingface/provider-catalog.ts
+++ b/extensions/huggingface/provider-catalog.ts
@ -0,0 +1,22 @@
+import {
+  buildHuggingfaceModelDefinition,
+  discoverHuggingfaceModels,
+  HUGGINGFACE_BASE_URL,
+  HUGGINGFACE_MODEL_CATALOG,
+} from "../../src/agents/huggingface-models.js";
+import type { ModelProviderConfig } from "../../src/config/types.models.js";
+
+export async function buildHuggingfaceProvider(
+  discoveryApiKey?: string,
+): Promise<ModelProviderConfig> {
+  const resolvedSecret = discoveryApiKey?.trim() ?? "";
+  const models =
+    resolvedSecret !== ""
+      ? await discoverHuggingfaceModels(resolvedSecret)
+      : HUGGINGFACE_MODEL_CATALOG.map(buildHuggingfaceModelDefinition);
+  return {
+    baseUrl: HUGGINGFACE_BASE_URL,
+    api: "openai-completions",
+    models,
+  };
+}
--- a/extensions/imessage/index.ts
+++ b/extensions/imessage/index.ts
@ -1,5 +1,5 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { imessagePlugin } from "./src/channel.js";
 import { setIMessageRuntime } from "./src/runtime.js";

--- a/extensions/imessage/src/accounts.ts
+++ b/extensions/imessage/src/accounts.ts
@ -1,7 +1,10 @@
-import { normalizeAccountId, type IMessageAccountConfig } from "openclaw/plugin-sdk/imessage";
-import { createAccountListHelpers } from "../../../src/channels/plugins/account-helpers.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import { resolveAccountEntry } from "../../../src/routing/account-lookup.js";
+import type { IMessageAccountConfig } from "openclaw/plugin-sdk/imessage";
+import {
+  type OpenClawConfig,
+  createAccountListHelpers,
+  normalizeAccountId,
+  resolveAccountEntry,
+} from "../../../src/plugin-sdk-internal/accounts.js";

 export type ResolvedIMessageAccount = {
  accountId: string;
--- a/extensions/imessage/src/probe.test.ts
+++ b/extensions/imessage/src/probe.test.ts
@ -1,36 +1,30 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as onboardHelpers from "../../../src/commands/onboard-helpers.js";
+import * as execModule from "../../../src/process/exec.js";
+import * as clientModule from "./client.js";
 import { probeIMessage } from "./probe.js";

-const detectBinaryMock = vi.hoisted(() => vi.fn());
-const runCommandWithTimeoutMock = vi.hoisted(() => vi.fn());
-const createIMessageRpcClientMock = vi.hoisted(() => vi.fn());
-
-vi.mock("../../../src/commands/onboard-helpers.js", () => ({
-  detectBinary: (...args: unknown[]) => detectBinaryMock(...args),
-}));
-
-vi.mock("../../../src/process/exec.js", () => ({
-  runCommandWithTimeout: (...args: unknown[]) => runCommandWithTimeoutMock(...args),
-}));
-
-vi.mock("./client.js", () => ({
-  createIMessageRpcClient: (...args: unknown[]) => createIMessageRpcClientMock(...args),
-}));
-
 beforeEach(() => {
-  detectBinaryMock.mockClear().mockResolvedValue(true);
-  runCommandWithTimeoutMock.mockClear().mockResolvedValue({
+  vi.restoreAllMocks();
+  vi.spyOn(onboardHelpers, "detectBinary").mockResolvedValue(true);
+  vi.spyOn(execModule, "runCommandWithTimeout").mockResolvedValue({
    stdout: "",
    stderr: 'unknown command "rpc" for "imsg"',
    code: 1,
    signal: null,
    killed: false,
+    termination: "exit",
  });
-  createIMessageRpcClientMock.mockClear();
 });

 describe("probeIMessage", () => {
  it("marks unknown rpc subcommand as fatal", async () => {
+    const createIMessageRpcClientMock = vi
+      .spyOn(clientModule, "createIMessageRpcClient")
+      .mockResolvedValue({
+        request: vi.fn(),
+        stop: vi.fn(),
+      } as unknown as Awaited<ReturnType<typeof clientModule.createIMessageRpcClient>>);
    const result = await probeIMessage(1000, { cliPath: "imsg" });
    expect(result.ok).toBe(false);
    expect(result.fatal).toBe(true);
--- a/extensions/imessage/src/runtime.ts
+++ b/extensions/imessage/src/runtime.ts
@ -1,5 +1,5 @@
-import type { PluginRuntime } from "openclaw/plugin-sdk";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/compat";
+import type { PluginRuntime } from "openclaw/plugin-sdk/core";

 const { setRuntime: setIMessageRuntime, getRuntime: getIMessageRuntime } =
  createPluginRuntimeStore<PluginRuntime>("iMessage runtime not initialized");
--- a/extensions/imessage/src/setup-core.ts
+++ b/extensions/imessage/src/setup-core.ts
@ -1,20 +1,21 @@
 import {
  applyAccountNameToChannelSection,
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
  migrateBaseNameToDefaultAccount,
-} from "../../../src/channels/plugins/setup-helpers.js";
-import {
+  normalizeAccountId,
  parseSetupEntriesAllowingWildcard,
  promptParsedAllowFromForScopedChannel,
  setChannelDmPolicyWithAllowFrom,
  setSetupChannelEnabled,
-} from "../../../src/channels/plugins/setup-wizard-helpers.js";
-import type { ChannelSetupDmPolicy } from "../../../src/channels/plugins/setup-wizard-types.js";
-import { type ChannelSetupWizard } from "../../../src/channels/plugins/setup-wizard.js";
-import type { ChannelSetupAdapter } from "../../../src/channels/plugins/types.adapters.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "../../../src/routing/session-key.js";
-import { formatDocsLink } from "../../../src/terminal/links.js";
-import type { WizardPrompter } from "../../../src/wizard/prompts.js";
+  type OpenClawConfig,
+  type WizardPrompter,
+} from "../../../src/plugin-sdk-internal/setup.js";
+import type {
+  ChannelSetupAdapter,
+  ChannelSetupDmPolicy,
+  ChannelSetupWizard,
+} from "../../../src/plugin-sdk-internal/setup.js";
 import {
  listIMessageAccountIds,
  resolveDefaultIMessageAccountId,
--- a/extensions/imessage/src/setup-surface.ts
+++ b/extensions/imessage/src/setup-surface.ts
@ -1,16 +1,18 @@
 import {
+  DEFAULT_ACCOUNT_ID,
+  detectBinary,
+  formatDocsLink,
+  type OpenClawConfig,
  parseSetupEntriesAllowingWildcard,
  promptParsedAllowFromForScopedChannel,
  setChannelDmPolicyWithAllowFrom,
  setSetupChannelEnabled,
-} from "../../../src/channels/plugins/setup-wizard-helpers.js";
-import type { ChannelSetupDmPolicy } from "../../../src/channels/plugins/setup-wizard-types.js";
-import { type ChannelSetupWizard } from "../../../src/channels/plugins/setup-wizard.js";
-import { detectBinary } from "../../../src/commands/onboard-helpers.js";
-import type { OpenClawConfig } from "../../../src/config/config.js";
-import { DEFAULT_ACCOUNT_ID } from "../../../src/routing/session-key.js";
-import { formatDocsLink } from "../../../src/terminal/links.js";
-import type { WizardPrompter } from "../../../src/wizard/prompts.js";
+  type WizardPrompter,
+} from "../../../src/plugin-sdk-internal/setup.js";
+import type {
+  ChannelSetupDmPolicy,
+  ChannelSetupWizard,
+} from "../../../src/plugin-sdk-internal/setup.js";
 import {
  listIMessageAccountIds,
  resolveDefaultIMessageAccountId,
--- a/extensions/kilocode/index.ts
+++ b/extensions/kilocode/index.ts
@ -1,5 +1,4 @@
 import { emptyPluginConfigSchema, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { buildKilocodeProviderWithDiscovery } from "../../src/agents/models-config.providers.discovery.js";
 import {
  createKilocodeWrapper,
  isProxyReasoningUnsupported,
@ -9,6 +8,7 @@ import {
  KILOCODE_DEFAULT_MODEL_REF,
 } from "../../src/commands/onboard-auth.js";
 import { createProviderApiKeyAuthMethod } from "../../src/plugins/provider-api-key-auth.js";
+import { buildKilocodeProviderWithDiscovery } from "./provider-catalog.js";

 const PROVIDER_ID = "kilocode";

--- a/extensions/kilocode/provider-catalog.ts
+++ b/extensions/kilocode/provider-catalog.ts
@ -0,0 +1,34 @@
+import { discoverKilocodeModels } from "../../src/agents/kilocode-models.js";
+import type { ModelProviderConfig } from "../../src/config/types.models.js";
+import {
+  KILOCODE_BASE_URL,
+  KILOCODE_DEFAULT_CONTEXT_WINDOW,
+  KILOCODE_DEFAULT_COST,
+  KILOCODE_DEFAULT_MAX_TOKENS,
+  KILOCODE_MODEL_CATALOG,
+} from "../../src/providers/kilocode-shared.js";
+
+export function buildKilocodeProvider(): ModelProviderConfig {
+  return {
+    baseUrl: KILOCODE_BASE_URL,
+    api: "openai-completions",
+    models: KILOCODE_MODEL_CATALOG.map((model) => ({
+      id: model.id,
+      name: model.name,
+      reasoning: model.reasoning,
+      input: model.input,
+      cost: KILOCODE_DEFAULT_COST,
+      contextWindow: model.contextWindow ?? KILOCODE_DEFAULT_CONTEXT_WINDOW,
+      maxTokens: model.maxTokens ?? KILOCODE_DEFAULT_MAX_TOKENS,
+    })),
+  };
+}
+
+export async function buildKilocodeProviderWithDiscovery(): Promise<ModelProviderConfig> {
+  const models = await discoverKilocodeModels();
+  return {
+    baseUrl: KILOCODE_BASE_URL,
+    api: "openai-completions",
+    models,
+  };
+}
--- a/extensions/kimi-coding/index.ts
+++ b/extensions/kimi-coding/index.ts
@ -1,8 +1,8 @@
 import { emptyPluginConfigSchema, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
-import { buildKimiCodingProvider } from "../../src/agents/models-config.providers.static.js";
 import { applyKimiCodeConfig, KIMI_CODING_MODEL_REF } from "../../src/commands/onboard-auth.js";
 import { createProviderApiKeyAuthMethod } from "../../src/plugins/provider-api-key-auth.js";
 import { isRecord } from "../../src/utils.js";
+import { buildKimiCodingProvider } from "./provider-catalog.js";

 const PROVIDER_ID = "kimi-coding";

--- a/extensions/kimi-coding/provider-catalog.ts
+++ b/extensions/kimi-coding/provider-catalog.ts
@ -0,0 +1,34 @@
+import type { ModelProviderConfig } from "../../src/config/types.models.js";
+
+export const KIMI_CODING_BASE_URL = "https://api.kimi.com/coding/";
+const KIMI_CODING_USER_AGENT = "claude-code/0.1.0";
+export const KIMI_CODING_DEFAULT_MODEL_ID = "k2p5";
+const KIMI_CODING_DEFAULT_CONTEXT_WINDOW = 262144;
+const KIMI_CODING_DEFAULT_MAX_TOKENS = 32768;
+const KIMI_CODING_DEFAULT_COST = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+};
+
+export function buildKimiCodingProvider(): ModelProviderConfig {
+  return {
+    baseUrl: KIMI_CODING_BASE_URL,
+    api: "anthropic-messages",
+    headers: {
+      "User-Agent": KIMI_CODING_USER_AGENT,
+    },
+    models: [
+      {
+        id: KIMI_CODING_DEFAULT_MODEL_ID,
+        name: "Kimi for Coding",
+        reasoning: true,
+        input: ["text", "image"],
+        cost: KIMI_CODING_DEFAULT_COST,
+        contextWindow: KIMI_CODING_DEFAULT_CONTEXT_WINDOW,
+        maxTokens: KIMI_CODING_DEFAULT_MAX_TOKENS,
+      },
+    ],
+  };
+}
--- a/extensions/llm-task/src/llm-task-tool.test.ts
+++ b/extensions/llm-task/src/llm-task-tool.test.ts
@ -1,17 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-
-vi.mock("openclaw/extension-api", () => {
-  return {
-    runEmbeddedPiAgent: vi.fn(async () => ({
-      meta: { startedAt: Date.now() },
-      payloads: [{ text: "{}" }],
-    })),
-  };
-});
-
-import { runEmbeddedPiAgent } from "openclaw/extension-api";
 import { createLlmTaskTool } from "./llm-task-tool.js";

+const runEmbeddedPiAgent = vi.fn(async () => ({
+  meta: { startedAt: Date.now() },
+  payloads: [{ text: "{}" }],
+}));
+
 // oxlint-disable-next-line typescript/no-explicit-any
 function fakeApi(overrides: any = {}) {
  return {
@ -22,7 +16,12 @@ function fakeApi(overrides: any = {}) {
      agents: { defaults: { workspace: "/tmp", model: { primary: "openai-codex/gpt-5.2" } } },
    },
    pluginConfig: {},
-    runtime: { version: "test" },
+    runtime: {
+      version: "test",
+      agent: {
+        runEmbeddedPiAgent,
+      },
+    },
    logger: { debug() {}, info() {}, warn() {}, error() {} },
    registerTool() {},
    ...overrides,
--- a/Show More
+++ b/Show More