fix(memory): exclude peer dream artifacts from extra paths

(cherry picked from commit 7cd774a665)

.agents/skills/channel-message-flows/SKILL.md

@@ -1,34 +1,44 @@
 ---
 name: channel-message-flows
-description: "Use when running QA Lab channel message flow evidence."
+description: "Use when previewing local channel message flow fixtures."
 ---
 
 # Channel Message Flows
 
-Use this from the OpenClaw repo root to run the QA Lab evidence for Telegram
-draft/final delivery sequencing. This skill no longer launches a standalone
-script; the behavior is owned by the QA scenario and its Vitest-backed e2e test.
+Use this from the OpenClaw repo root to send canned channel preview flows while iterating on message UX. These are real sends/edits/deletes against the configured channel target.
 
-## QA Scenario
+## Telegram
 
-Run the scenario through QA Lab:
+Native Telegram `sendMessageDraft` tool progress, then a final answer:
 
 ```bash
-pnpm openclaw qa suite --scenario channel-message-flows
+node --import tsx scripts/dev/channel-message-flows.ts \
+  --channel telegram \
+  --target <telegram-chat-id> \
+  --flow working-final \
+  --duration-ms 20000
 ```
 
-Run the focused e2e test directly in a Codex worktree:
+Thinking preview, then a final answer:
 
 ```bash
-node scripts/run-vitest.mjs test/e2e/qa-lab/channels/channel-message-flows.e2e.test.ts
+node --import tsx scripts/dev/channel-message-flows.ts \
+  --channel telegram \
+  --target <telegram-chat-id> \
+  --flow thinking-final
 ```
 
-## References
+## Options
 
-- `qa/scenarios/channels/channel-message-flows.yaml`
-- `test/e2e/qa-lab/channels/channel-message-flows.e2e.test.ts`
-- `test/e2e/qa-lab/channels/channel-message-flows-runtime.ts`
+- `--account <accountId>`: Telegram account id when not using the default.
+- `--thread-id <id>`: Telegram forum topic/message thread id.
+- `--delay-ms <ms>`: Override preview update cadence.
+- `--duration-ms <ms>`: Simulated working duration for `working-final`.
+- `--final-text <text>`: Override the durable final message.
 
-The scenario covers `channels.streaming` as primary evidence and records
-secondary coverage for thread preservation, delivery ordering, and reasoning
-preview visibility.
+## Notes
+
+- `--target` is the numeric Telegram chat id.
+- `working-final` exercises native Telegram `sendMessageDraft` with static `Working` status and sample tool progress.
+- `thinking-final` exercises formatted `Thinking` reasoning preview clearing before the final answer.
+- Only `--channel telegram` is implemented for now.

.agents/skills/openclaw-changelog-update/SKILL.md

@@ -12,10 +12,10 @@ content, ordering, grouping, and attribution discipline.
 
 ## Goal
 
-Rewrite the target `CHANGELOG.md` version section from history, not from stale
-draft notes. Produce grouped user-facing release notes sorted by user interest
-while preserving every relevant issue/PR ref and every human `Thanks @...`
-attribution.
+Rebuild the target `CHANGELOG.md` version section from a complete, generated
+history manifest, not stale draft notes. Produce grouped user-facing release
+notes sorted by user interest while preserving every relevant issue/PR ref and
+every human `Thanks @...` attribution.
 
 ## Inputs
 
@@ -34,8 +34,37 @@ attribution.
    - `git log --first-parent --date=iso-strict --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>`
    - `git log --first-parent --grep='(#' --date=short --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>`
    - also inspect `--since='24 hours ago'` when main moved during the release.
-3. Read linked PRs/issues or diffs for ambiguous commits. Direct commits matter;
-   infer notes from subject, body, touched files, tests, and nearby commits.
+3. Generate the complete contribution record and editorial manifest before
+   writing grouped prose:
+
+   ```bash
+   node .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
+     --base <base-tag> \
+     --target <target-ref> \
+     --version <YYYY.M.PATCH> \
+     --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
+     --write-ledger
+   ```
+
+   - the manifest is the required input to the rewrite, not an after-the-fact
+     audit; it contains every referenced PR, eligible contributor credit,
+     inline issue context, every direct commit, and an editorial-eligibility
+     classification for PRs and direct commits
+   - for a historical backfill, add `--seed-ref <pre-backfill-ref>` once so
+     contribution records from the prior changelog are retained even when an
+     older merged commit omitted its PR number; the verifier excludes records
+     for work reverted after the base tag, including beta work reverted before
+     the stable release
+   - source PR discovery combines merged GitHub commit associations with merged
+     PR references explicitly present in active commit subjects/bodies so
+     cherry-picks and squash commits remain accounted for. Resolve every
+     association page and exclude PRs merged after the target release commit
+   - read the manifest before editing `### Highlights`, `### Changes`, or
+     `### Fixes`; do not carry old grouped prose forward without re-auditing it
+   - inspect linked PRs/issues or diffs for ambiguous commits. Direct commits
+     are editorial input, not public ledger rows; infer material user outcomes
+     from subject, body, touched files, tests, and nearby commits
+
 4. Rewrite one stable-base section only:
    - use `## YYYY.M.PATCH`
    - do not create beta-specific headings
@@ -44,10 +73,21 @@ attribution.
      section instead of deleting them
 5. Section shape:
    - `### Highlights`: 5-8 bullets, broad user wins first
+     - include only a clear user-visible capability or workflow unlock, a
+       material reliability/safety fix, a broad cross-surface improvement, or
+       a release-defining integration/compatibility milestone
+     - every highlight must say what changed for a user in one sentence; use
+       one user story per bullet and group its supporting PRs
+     - exclude tests, CI, refactors, docs, catalog churn, and implementation
+       detail unless the outcome is a material install/update, data-safety, or
+       widely visible user improvement
    - `### Changes`: new capabilities and behavior changes
    - `### Fixes`: user-facing fixes first, grouped by impact and surface
    - group related changes/fixes by surface and user impact; avoid one bullet
      per tiny commit when several commits tell one user-facing story
+   - `### Complete contribution record`: generated PR-first record after the
+     grouped prose; it is the exhaustive accounting surface, not a second
+     release summary
 6. Preserve attribution:
    - keep `#issue`, `(#PR)`, `Fixes #...`, and `Thanks @...`
    - every human-authored merged PR represented by a user-facing entry needs
@@ -62,17 +102,35 @@ attribution.
    - multiple `Thanks @...` handles in one bullet are expected; do not drop or
      collapse contributor credit just because the note is grouped
    - if one grouped bullet covers both direct commits and PRs, keep all PR refs
-     and thanks, plus any issue refs from the direct commits
-   - before finalizing, audit the final release-note body:
-     - extract all `#NNN` refs from the notes
-     - resolve which refs are PRs and collect human PR authors
-     - resolve issue refs used as bug/report refs and collect human reporters
-     - scan represented commits for `Co-authored-by`
-     - compare those handles to the final `Thanks @...` set
-     - fix every missing human credit or explicitly record why it is omitted
+     and thanks, plus any issue refs and human credit from the direct work
+   - issues remain normal inline `#NNN` references. Do not add a separate
+     linked-issues inventory. The generated PR record keeps source issues
+     inline as `Related #NNN` on the PR that shipped them
+   - when backfilling an older linked-issues inventory, preserve reporter
+     credit inline for every GitHub-confirmed closing PR relationship. Do not
+     infer a PR relationship from a generic cross-reference event, invent an
+     unrelated PR link for a standalone report, or recreate the retired
+     inventory
+   - the complete contribution record lists every merged source PR exactly once
+     as `**PR #NNN**`; source PRs include GitHub commit associations and merged
+     PR references explicitly present in active commit subjects/bodies. It
+     preserves author/co-author credit and any issue references in the original
+     title
+   - direct commits remain in the manifest with GitHub-resolved author,
+     co-author, issue, and editorial-eligibility data. They inform grouped
+     prose but are never rendered as a public `#### Direct commits` dump. Add
+     direct-commit credit to a grouped bullet only when it shares an explicit
+     closing issue reference or at least two distinctive subject terms
+   - the verifier rejects `docs`, `test`, `refactor`, `ci`, `build`, `chore`,
+     and `style` PRs in Highlights, Changes, or Fixes. Keep those internal
+     contributions in the complete PR record, but do not give them editorial
+     release-note space
+   - classify internal-only work from conventional prefixes and clear title
+     signals such as `QA`, `test`, `docs`, `refactor`, `lint`, or `CI`; an
+     untyped title is not automatically editorial
    - do not add GHSA references, advisory IDs, or security advisory slugs to
      changelog entries or GitHub release-note text unless explicitly requested
-   - never thank bots, `@openclaw`, `@clawsweeper`, or `@steipete`
+   - never thank bots, `@claude`, `@openclaw`, `@clawsweeper`, or `@steipete`
    - do not use GitHub's release contributor count as the source of truth; the
      changelog must carry the complete human credit set itself
 7. Sorting preference:
@@ -91,36 +149,50 @@ attribution.
    - if any compatibility `removeAfter` is on/before release date, resolve it
      or explicitly record the blocker before shipping
 10. Validate and ship:
-   - generate and verify the complete contribution ledger before committing:
-     ```bash
-     node .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
-       --base <base-tag> \
-       --target <target-ref> \
-       --version <YYYY.M.PATCH> \
-       --write-ledger
-     ```
-   - the command fails when any `#NNN` reference in release history or the
-     rendered release section is absent from the ledger, when reverted work is
-     presented as shipped, or when an eligible PR author, issue reporter, or
-     known co-author is missing from that entry's `Thanks @...` credit
-   - after the GitHub release or prerelease is published, verify every matching
-     release page against the same source section:
-     ```bash
-     node .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
-       --base <base-tag> \
-       --target <target-ref> \
-       --version <YYYY.M.PATCH> \
-       --release-tag v<YYYY.M.PATCH> \
-       --check-github
-     ```
-   - add one `--release-tag` for every beta and stable page in the train; a
-     `### Release verification` tail is permitted, but any other body drift
-     fails the check; the GitHub body must begin with the complete
-     `## YYYY.M.PATCH` changelog section, including its heading
-   - `git diff --check`
-   - for docs/changelog-only changes, no broad tests are required
-   - commit with `scripts/committer "docs(changelog): refresh YYYY.M.PATCH notes" CHANGELOG.md`
-   - push, pull/rebase if needed, then branch/rebase release from latest `main`
+
+- after the manifest-driven rewrite, regenerate and verify the complete
+  contribution record before committing:
+  ```bash
+  node .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
+    --base <base-tag> \
+    --target <target-ref> \
+    --version <YYYY.M.PATCH> \
+    --manifest /tmp/openclaw-release-<YYYY.M.PATCH>.json \
+    --write-ledger
+  ```
+- the command fails when any `#NNN` reference in release history or the
+  rendered release section cannot resolve, when reverted work is presented
+  as shipped, when a source PR is absent from the contribution record, when
+  direct commits are rendered as a public record dump, when non-editorial
+  PRs appear in grouped prose, or when an eligible PR author or known
+  co-author is missing from that PR's `Thanks @...` credit
+- when grouped prose names a PR, that same bullet must retain every
+  contributor and linked-reporter credit from its generated PR record
+- unqualified `#NNN` references resolve against `openclaw/openclaw`;
+  cross-repository references such as `openclaw/imsg#141` remain literal
+  text and must not be rewritten as local issue links
+- after the GitHub release or prerelease is published, verify every matching
+  release page against the same source section:
+  ```bash
+  node .agents/skills/openclaw-changelog-update/scripts/verify-release-notes.mjs \
+    --base <base-tag> \
+    --target <target-ref> \
+    --version <YYYY.M.PATCH> \
+    --release-tag v<YYYY.M.PATCH> \
+    --check-github
+  ```
+- add one `--release-tag` for every beta and stable page in the train; a
+  `### Release verification` tail is permitted, but any other body drift
+  fails the check; the GitHub body must begin with the complete
+  `## YYYY.M.PATCH` changelog section, including its heading
+- GitHub release bodies are limited to 125,000 characters. If the complete
+  source section plus an existing verification tail exceeds that limit, keep
+  the source section intact and omit the tail; never truncate the
+  contribution record
+- `git diff --check`
+- for docs/changelog-only changes, no broad tests are required
+- commit with `scripts/committer "docs(changelog): refresh YYYY.M.PATCH notes" CHANGELOG.md`
+- push, pull/rebase if needed, then branch/rebase release from latest `main`
 
 ## Quota / API Outage Rule
 

.agents/skills/release-openclaw-maintainer/SKILL.md

@@ -249,12 +249,20 @@ Stable publication is not complete until `main` carries the actual shipped relea
   section from history, not existing notes. Use the last reachable stable or
   beta release tag as the base, then inspect every commit through the target
   release SHA.
+- Generate `$openclaw-changelog-update`'s full contribution manifest before
+  the editorial rewrite. It is the required source for `### Highlights`,
+  `### Changes`, and `### Fixes`; do not preserve old grouped prose without
+  comparing it to the manifest's PRs, contributors, direct commits, and
+  unlinked commits.
 - The changelog rewrite is not optional for beta reruns: any `beta.N` after a
   rebase or backport must refresh the same stable-base `## YYYY.M.PATCH` section
   before the new version/tag commit.
 - Include both merged PR commits and direct commits on `main`. Direct commits
   matter: infer notes from their subject, body, touched files, linked issues,
   tests, and nearby code when no PR body exists.
+- Keep direct commits in the generated manifest and use them to shape grouped
+  user outcomes, but never dump them into `CHANGELOG.md` or GitHub release
+  bodies. The public complete record is PR-first and exhaustive for PRs.
 - Prefer PR bodies, issue links, review proof, and commit bodies over commit
   subjects alone. If a commit fixed an issue directly, the commit body should
   name the user-visible behavior, affected surface, issue ref, and credited
@@ -270,11 +278,31 @@ Stable publication is not complete until `main` carries the actual shipped relea
   `#issue`, `(#PR)`, `Fixes #...`, and every human `Thanks @...` handle.
   Multiple thanks in one bullet are expected when multiple contributor PRs are
   grouped.
+- Highlights earn their place only when they are a visible capability/workflow
+  unlock, a material reliability or safety repair, a broad user-facing
+  improvement, or a release-defining integration/compatibility change. Keep
+  five to eight user-outcome bullets; omit tests, CI, refactors, docs, and
+  implementation trivia unless their outcome materially affects users.
+- Do not give `docs`, `test`, `refactor`, `ci`, `build`, `chore`, or `style`
+  PRs/direct commits their own Highlights, Changes, or Fixes entry. They remain
+  accounted for in the PR record or manifest, but are not product release
+  content. Treat explicit internal title signals such as `QA`, `lint`, or
+  `testing` the same way even when the PR has no conventional prefix.
+- Use the generated `### Complete contribution record` as PR-first accounting:
+  every merged source PR appears once with author/co-author credit, including
+  PRs identified only by an explicit active-commit `#NNN` reference after a
+  cherry-pick or squash. Keep issues inline as `#NNN` in titles and grouped
+  prose; do not create a linked-issues inventory or a direct-commit listing.
+  When grouped prose names a PR, keep every contributor and linked-reporter
+  credit from that PR's record on the same bullet.
 - Changelog entries should be user-facing, not internal release-process notes.
 - GitHub release and prerelease bodies must use the full matching
   `CHANGELOG.md` version section, not highlights or an excerpt. When creating
   or editing a release, extract from `## YYYY.M.PATCH` through the line before the
   next level-2 heading and use that complete block as the release notes.
+- GitHub limits release bodies to 125,000 characters. If a historical
+  `### Release verification` tail would exceed that cap, omit the tail and keep
+  the complete changelog section; do not truncate the contribution record.
 - Before publishing or closing a release, run
   `$openclaw-changelog-update`'s `verify-release-notes.mjs` with every stable
   and beta release tag in the train. Do not publish or leave a page live when

.github/codeql/codeql-network-ssrf-boundary-critical-security.yml

@@ -20,7 +20,7 @@ paths:
   - src/agents/tools/web-shared.ts
   - src/plugin-sdk/ssrf-policy.ts
   - src/web-fetch
-  - src/web/provider-runtime-shared.ts
+  - packages/web-content-core/src/provider-runtime-shared.ts
   - packages/memory-host-sdk/src/host/ssrf-policy.ts
   - packages/net-policy/src
 

.github/codeql/codeql-web-media-runtime-boundary-critical-quality.yml

@@ -16,7 +16,7 @@ query-filters:
 paths:
   - src/web-fetch
   - src/web-search
-  - src/web/provider-runtime-shared.ts
+  - packages/web-content-core/src/provider-runtime-shared.ts
   - src/media
   - src/media-understanding
   - src/image-generation

.github/workflows/windows-testbox-probe.yml

@@ -37,6 +37,11 @@ on:
         required: false
         default: false
         type: boolean
+      run_windows_ci:
+        description: "Run the focused Windows-native CI test shard after probing"
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: read
@@ -84,6 +89,7 @@ jobs:
         run: |
           $ErrorActionPreference = "Continue"
           $ok = $false
+          $restartRequired = $false
 
           function Invoke-WslText {
             param([string[]] $Arguments)
@@ -112,9 +118,15 @@ jobs:
             Write-Host "wsl.exe=$($wsl.Source)"
             if ($env:ENABLE_WSL2_FEATURES -eq "true") {
               Write-Host "enable_wsl2_features=true"
-              foreach ($feature in @("Microsoft-Windows-Subsystem-Linux", "VirtualMachinePlatform", "HypervisorPlatform", "Microsoft-Hyper-V-All")) {
+              foreach ($feature in @("Microsoft-Windows-Subsystem-Linux", "VirtualMachinePlatform", "HypervisorPlatform")) {
                 dism.exe /online /enable-feature /featurename:$feature /all /norestart
                 Write-Host "enable_feature_${feature}_exit=$LASTEXITCODE"
+                if ($LASTEXITCODE -eq 3010) {
+                  $restartRequired = $true
+                }
+              }
+              if ($restartRequired) {
+                Write-Warning "wsl2_restart_required=true; Windows optional feature changes require a runner reboot before WSL2 can be imported."
               }
             }
 
@@ -127,7 +139,7 @@ jobs:
             Write-Host "wsl_list_exit=$($list.Code)"
 
             $distros = @(Get-WslDistros)
-            if ($distros.Count -eq 0 -and $env:IMPORT_UBUNTU_WSL2 -eq "true") {
+            if ($distros.Count -eq 0 -and $env:IMPORT_UBUNTU_WSL2 -eq "true" -and -not $restartRequired) {
               Write-Host "import_ubuntu_wsl2=true"
               $wslRoot = "C:\wsl\UbuntuProbe"
               $rootfs = "C:\wsl\ubuntu-noble-wsl.rootfs.tar.gz"
@@ -140,12 +152,16 @@ jobs:
               Write-Host $list.Text
               Write-Host "wsl_list_after_import_exit=$($list.Code)"
               $distros = @(Get-WslDistros)
+            } elseif ($distros.Count -eq 0 -and $env:IMPORT_UBUNTU_WSL2 -eq "true" -and $restartRequired) {
+              Write-Warning "import_ubuntu_wsl2=skipped_restart_required"
             }
 
             if ($distros.Count -gt 0) {
               $distro = $distros[0]
               Write-Host "wsl_probe_distro=$distro"
               $exec = Invoke-WslText -Arguments @("-d", $distro, "--exec", "bash", "-lc", 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi')
+            } elseif ($restartRequired) {
+              $exec = [pscustomobject]@{ Code = 1; Text = "wsl_exec_skipped=restart_required" }
             } else {
               $exec = Invoke-WslText -Arguments @("--exec", "bash", "-lc", 'set -euo pipefail; uname -a; if [ -f /etc/os-release ]; then sed -n "1,8p" /etc/os-release; fi')
             }
@@ -158,17 +174,99 @@ jobs:
 
           if ($ok) {
             "wsl2_ok=true" >> $env:GITHUB_OUTPUT
+            "wsl2_restart_required=false" >> $env:GITHUB_OUTPUT
             "OPENCLAW_WSL2_PROBE_OK=true" >> $env:GITHUB_ENV
+            "OPENCLAW_WSL2_RESTART_REQUIRED=false" >> $env:GITHUB_ENV
             Write-Host "wsl2_ok=true"
           } else {
             "wsl2_ok=false" >> $env:GITHUB_OUTPUT
+            "wsl2_restart_required=$($restartRequired.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
             "OPENCLAW_WSL2_PROBE_OK=false" >> $env:GITHUB_ENV
+            "OPENCLAW_WSL2_RESTART_REQUIRED=$($restartRequired.ToString().ToLowerInvariant())" >> $env:GITHUB_ENV
             Write-Warning "wsl2_ok=false"
           }
 
           exit 0
 
+      - name: Try to exclude workspace from Windows Defender (best-effort)
+        if: ${{ inputs.run_windows_ci }}
+        shell: pwsh
+        run: |
+          $cmd = Get-Command Add-MpPreference -ErrorAction SilentlyContinue
+          if (-not $cmd) {
+            Write-Host "Add-MpPreference not available, skipping Defender exclusions."
+            exit 0
+          }
+
+          try {
+            Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE" -ErrorAction Stop
+            Add-MpPreference -ExclusionProcess "node.exe" -ErrorAction Stop
+            Write-Host "Defender exclusions applied."
+          } catch {
+            Write-Warning "Failed to apply Defender exclusions, continuing. $($_.Exception.Message)"
+          }
+
+      - name: Setup Node.js
+        if: ${{ inputs.run_windows_ci }}
+        shell: bash
+        env:
+          REQUESTED_NODE_VERSION: "22.x"
+        run: |
+          set -euo pipefail
+          source .github/actions/setup-pnpm-store-cache/ensure-node.sh
+          openclaw_ensure_node "$REQUESTED_NODE_VERSION"
+
+      - name: Setup pnpm
+        if: ${{ inputs.run_windows_ci }}
+        uses: ./.github/actions/setup-pnpm-store-cache
+        with:
+          node-version: 22.x
+
+      - name: Runtime versions
+        if: ${{ inputs.run_windows_ci }}
+        shell: bash
+        run: |
+          node -v
+          npm -v
+          pnpm -v
+
+      - name: Capture node path
+        if: ${{ inputs.run_windows_ci }}
+        shell: bash
+        run: |
+          node_bin="$(dirname "$(node -p 'process.execPath')")"
+          if command -v cygpath >/dev/null 2>&1; then
+            node_bin="$(cygpath -u "$node_bin")"
+          fi
+          echo "NODE_BIN=$node_bin" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        if: ${{ inputs.run_windows_ci }}
+        shell: bash
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --prefer-offline --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true --config.side-effects-cache=true || pnpm install --frozen-lockfile --prefer-offline --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true --config.side-effects-cache=true
+
+      - name: Run Windows CI tests
+        if: ${{ inputs.run_windows_ci }}
+        shell: bash
+        env:
+          CI: true
+          NODE_OPTIONS: --max-old-space-size=8192
+          OPENCLAW_TEST_SKIP_FULL_EXTENSIONS_SHARD: 1
+          OPENCLAW_VITEST_MAX_WORKERS: 1
+        run: |
+          set -euo pipefail
+          export PATH="$NODE_BIN:$PATH"
+          pnpm test:windows:ci
+
       - name: Keep runner alive for SSH inspection
+        if: ${{ always() && !cancelled() }}
         env:
           KEEPALIVE_MINUTES: ${{ inputs.keepalive_minutes }}
         run: |
@@ -185,7 +283,7 @@ jobs:
           }
 
       - name: Enforce WSL2 requirement
-        if: ${{ inputs.require_wsl2 }}
+        if: ${{ always() && !cancelled() && inputs.require_wsl2 }}
         run: |
           if ($env:OPENCLAW_WSL2_PROBE_OK -ne "true") {
             Write-Error "WSL2 probe failed or WSL2 is unavailable on this Windows runner."

apps/android/README.md

@@ -69,6 +69,17 @@ Generate raw Google Play screenshots:
 pnpm android:screenshots
 ```
 
+To make screenshot capture own emulator startup, pass a named AVD:
+
+```bash
+ANDROID_SCREENSHOT_AVD=OpenClaw_QA_API35 pnpm android:screenshots
+```
+
+The screenshot script uses one connected ADB device when available. If none is
+connected and `ANDROID_SCREENSHOT_AVD` is set, it boots that emulator
+headlessly, waits for Android to finish booting, disables animations, captures
+the screenshots, then shuts down the emulator it started.
+
 `pnpm android:release:archive` builds signed release artifacts into `apps/android/build/release-artifacts/` and writes `.sha256` checksum files:
 
 - Play build: `openclaw-<version>-play-release.aab`

apps/android/VERSIONING.md

@@ -49,7 +49,7 @@ Recommended workflow:
 3. Update `apps/android/CHANGELOG.md`, then run `pnpm android:version:sync` again if needed.
 4. Run `MATCH_PASSWORD=<signing repo password> pnpm android:release:signing:sync:pull` to materialize encrypted Android signing assets from `apps-signing`.
 5. Run `pnpm android:release:preflight` to validate Play auth, signing, synced versioning, and release notes.
-6. Run `pnpm android:screenshots` to refresh raw Google Play screenshots.
+6. Run `ANDROID_SCREENSHOT_AVD=<avd-name> pnpm android:screenshots` to refresh raw Google Play screenshots with a script-managed emulator, or run `pnpm android:screenshots` when exactly one ADB device is already connected.
 7. Run `pnpm android:release:archive` to produce the signed Play AAB and third-party APK.
 8. Run `pnpm android:release:upload` to upload metadata, screenshots, and the Play AAB to Google Play internal testing.
 9. Promote to production manually in Google Play Console.

apps/android/app/src/main/java/ai/openclaw/app/NodeForegroundService.kt

@@ -223,10 +223,11 @@ class NodeForegroundService : Service() {
 
 internal fun foregroundServiceTypesForVoiceMode(mode: VoiceCaptureMode): Int {
   val base = ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE
-  return if (mode == VoiceCaptureMode.TalkMode) {
-    base or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
-  } else {
-    base
+  return when (mode) {
+    VoiceCaptureMode.Off -> base
+    VoiceCaptureMode.ManualMic,
+    VoiceCaptureMode.TalkMode,
+    -> base or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
   }
 }
 

apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt

@@ -1396,8 +1396,9 @@ class NodeRuntime(
     mode: VoiceCaptureMode,
     persistManualMic: Boolean = true,
   ) {
-    if (mode == VoiceCaptureMode.TalkMode && !hasRecordAudioPermission()) {
+    if (mode.requiresMicrophonePermission && !hasRecordAudioPermission()) {
       _voiceCaptureMode.value = VoiceCaptureMode.Off
+      prefs.setVoiceMicEnabled(false)
       externalAudioCaptureActive.value = false
       return
     }
@@ -1468,6 +1469,9 @@ class NodeRuntime(
     }
   }
 
+  private val VoiceCaptureMode.requiresMicrophonePermission: Boolean
+    get() = this == VoiceCaptureMode.ManualMic || this == VoiceCaptureMode.TalkMode
+
   fun refreshGatewayConnection() {
     val endpoint = connectedEndpoint
     if (endpoint == null) {

apps/android/app/src/main/java/ai/openclaw/app/ui/AndroidScreenshotModeScreen.kt

@@ -114,16 +114,12 @@ private fun ConnectScene() {
 
 @Composable
 private fun ChatScene() {
-  ChatBubble(label = "You", text = "Summarize the launch checklist before I start the release.")
+  ChatBubble(label = "You", text = "Hi Molty, are you there?")
   ChatBubble(
-    label = "OpenClaw",
-    text = "Android archive, Play metadata, and internal testing upload are ready. Screenshots are being refreshed now.",
+    label = "Molty",
+    text = "Always. Lurking in the shadows, exfoliating.",
     raised = true,
   )
-  CompactList(
-    title = "Working set",
-    rows = listOf("Release notes", "Play bundle", "Device screenshots"),
-  )
 }
 
 @Composable

apps/android/app/src/test/java/ai/openclaw/app/GatewayBootstrapAuthTest.kt

@@ -376,6 +376,25 @@ class GatewayBootstrapAuthTest {
     assertNull(authStore.loadToken(deviceId, "operator"))
   }
 
+  @Test
+  fun restoredManualMicWithoutRecordAudioClearsStalePreference() {
+    val app = RuntimeEnvironment.getApplication()
+    shadowOf(app).denyPermissions(Manifest.permission.RECORD_AUDIO)
+    val securePrefs =
+      app.getSharedPreferences(
+        "openclaw.node.secure.test.${UUID.randomUUID()}",
+        android.content.Context.MODE_PRIVATE,
+      )
+    val prefs = SecurePrefs(app, securePrefsOverride = securePrefs)
+    prefs.setVoiceMicEnabled(true)
+
+    val runtime = NodeRuntime(app, prefs)
+
+    assertEquals(VoiceCaptureMode.Off, runtime.voiceCaptureMode.value)
+    assertFalse(prefs.voiceMicEnabled.value)
+    assertFalse(readField<MutableStateFlow<Boolean>>(runtime, "externalAudioCaptureActive").value)
+  }
+
   @Test
   fun talkPttStart_cleansPreparedCaptureWhenBeginFails() =
     runBlocking {

apps/android/app/src/test/java/ai/openclaw/app/NodeForegroundServiceTest.kt

@@ -32,13 +32,13 @@ class NodeForegroundServiceTest {
   }
 
   @Test
-  fun foregroundServiceTypesForVoiceMode_addsMicrophoneOnlyForTalkMode() {
+  fun foregroundServiceTypesForVoiceMode_addsMicrophoneForActiveCaptureModes() {
     assertEquals(
       ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
       foregroundServiceTypesForVoiceMode(VoiceCaptureMode.Off),
     )
     assertEquals(
-      ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE,
+      ServiceInfo.FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE,
       foregroundServiceTypesForVoiceMode(VoiceCaptureMode.ManualMic),
     )
     assertEquals(

apps/android/fastlane/Fastfile

@@ -6,6 +6,7 @@ require "supply/client"
 
 default_platform(:android)
 
+ANDROID_FASTLANE_ROOT = File.expand_path(__dir__, Dir.pwd)
 DEFAULT_PLAY_PACKAGE_NAME = "ai.openclaw.app"
 DEFAULT_PLAY_TRACK = "internal"
 DEFAULT_PLAY_RELEASE_STATUS = "completed"
@@ -35,7 +36,7 @@ def env_present?(value)
 end
 
 def android_root
-  File.expand_path("..", __dir__)
+  File.expand_path("..", ANDROID_FASTLANE_ROOT)
 end
 
 def repo_root
@@ -147,7 +148,7 @@ def sync_android_versioning!
 end
 
 def android_release_notes_path
-  File.join(__dir__, "metadata", "android", "en-US", "release_notes.txt")
+  File.join(ANDROID_FASTLANE_ROOT, "metadata", "android", "en-US", "release_notes.txt")
 end
 
 def validate_android_release_notes!
@@ -157,7 +158,7 @@ def validate_android_release_notes!
 end
 
 def android_changelog_path(version_code)
-  File.join(__dir__, "metadata", "android", "en-US", "changelogs", "#{version_code}.txt")
+  File.join(ANDROID_FASTLANE_ROOT, "metadata", "android", "en-US", "changelogs", "#{version_code}.txt")
 end
 
 def sync_android_changelog!(version_code)
@@ -170,7 +171,7 @@ def sync_android_changelog!(version_code)
 end
 
 def play_metadata_path
-  File.join(__dir__, "metadata", "android")
+  File.join(ANDROID_FASTLANE_ROOT, "metadata", "android")
 end
 
 def play_screenshot_paths
@@ -303,7 +304,7 @@ def upload_play_store_build!(version_metadata, upload_metadata: false, upload_im
   )
 end
 
-load_env_file(File.join(__dir__, ".env"))
+load_env_file(File.join(ANDROID_FASTLANE_ROOT, ".env"))
 
 platform :android do
   desc "Validate Google Play API credentials"

apps/android/fastlane/SETUP.md

@@ -65,9 +65,14 @@ pnpm android:release:archive
 Generate deterministic Google Play screenshots:
 
 ```bash
-pnpm android:screenshots
+ANDROID_SCREENSHOT_AVD=OpenClaw_QA_API35 pnpm android:screenshots
 ```
 
+If exactly one ADB device is already connected, `pnpm android:screenshots`
+uses it. With `ANDROID_SCREENSHOT_AVD` or `--avd <name>`, the script can boot a
+headless emulator, wait for boot completion, stabilize animation settings,
+capture screenshots, and shut down only the emulator it started.
+
 Upload metadata, release notes, and the Play AAB to the internal testing track:
 
 ```bash

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -6579,6 +6579,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
     public let security: AnyCodable?
     public let ask: AnyCodable?
     public let warningtext: AnyCodable?
+    public let unavailabledecisions: [String]?
     public let commandspans: [[String: AnyCodable]]?
     public let agentid: AnyCodable?
     public let resolvedpath: AnyCodable?
@@ -6604,6 +6605,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         security: AnyCodable?,
         ask: AnyCodable?,
         warningtext: AnyCodable?,
+        unavailabledecisions: [String]?,
         commandspans: [[String: AnyCodable]]?,
         agentid: AnyCodable? = nil,
         resolvedpath: AnyCodable?,
@@ -6628,6 +6630,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         self.security = security
         self.ask = ask
         self.warningtext = warningtext
+        self.unavailabledecisions = unavailabledecisions
         self.commandspans = commandspans
         self.agentid = agentid
         self.resolvedpath = resolvedpath
@@ -6654,6 +6657,7 @@ public struct ExecApprovalRequestParams: Codable, Sendable {
         case security
         case ask
         case warningtext = "warningText"
+        case unavailabledecisions = "unavailableDecisions"
         case commandspans = "commandSpans"
         case agentid = "agentId"
         case resolvedpath = "resolvedPath"

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-b7ec57a4f38bf44677870fd9a8347be83f3f23a25a73d97931406f0eff572181  config-baseline.json
-99d506f05de601e5b45c98f302650c8608d1e2bb3dcea11bf97881c1263659ac  config-baseline.core.json
+e78623d6eace69e46950cd5d9a5cf14aa910dac1ecdf9d054a0bd9999e936061  config-baseline.json
+5ecafa3c9a59fc0675f964f6e3238b2f20625376ebad1835278c5dd7323770d3  config-baseline.core.json
 2d735389858305509528e74329b6f8c65d311e1471c3b4e91dc17aaab8e63a80  config-baseline.channel.json
-a973af69b02a27b097b54e49886dd57dbebbc95e2ab29b0c7e222a9f35a105d8  config-baseline.plugin.json
+7c2c51b795d32e4c4c325080d59fec8fd11317c41db7db642f70e436779738bc  config-baseline.plugin.json

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -1,2 +1,2 @@
-c84eab270f19d11a807ce71e783d35ee95a7620295dbffcca7fff31dacfcc882  plugin-sdk-api-baseline.json
-55656396a5f1941af61603402c43e23e0ffc90003e7efa7c1857c4541a0f1bb4  plugin-sdk-api-baseline.jsonl
+7b0d7f0a21c91718fd05151778bb8ff1f16b622599c4dd0a868d72459ad08559  plugin-sdk-api-baseline.json
+65e710ce7c379b49abf1f5d1b4ef7b4cbabf2820be87f7f300f2988f05f63ec5  plugin-sdk-api-baseline.jsonl

docs/channels/slack.md

@@ -529,7 +529,7 @@ Notes:
 - `socketMode` is ignored in HTTP Request URL mode.
 - Base `channels.slack.socketMode` settings apply to all Slack accounts unless overridden. Per-account overrides use `channels.slack.accounts.<accountId>.socketMode`; because this is an object override, include every socket tuning field you want for that account.
 - Only `clientPingTimeout` has an OpenClaw default (`15000`). `serverPingTimeout` and `pingPongLoggingEnabled` are passed to the Slack SDK only when configured.
-- Socket Mode restart backoff starts around 2 seconds and caps around 30 seconds. Consecutive recoverable start/start-wait failures stop after 12 attempts; after a successful connection, later recoverable disconnects start a fresh retry cycle. Non-recoverable Slack auth errors such as `invalid_auth`, revoked tokens, or missing scopes fail fast instead of retrying forever.
+- Socket Mode restart backoff starts around 2 seconds and caps around 30 seconds. Recoverable start, start-wait, and disconnect failures retry until the channel stops. Permanent account and credential errors such as invalid auth, revoked tokens, or missing scopes fail fast instead of retrying forever.
 
 ## Manifest and scope checklist
 

docs/cli/infer.md

@@ -189,6 +189,7 @@ Use `image` for generation, edit, and description.
 openclaw infer image generate --prompt "friendly lobster illustration" --json
 openclaw infer image generate --prompt "cinematic product photo of headphones" --json
 openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
+openclaw infer image generate --model openai/gpt-image-2 --quality low --openai-moderation low --prompt "low-cost draft poster" --json
 openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
 openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
 openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
@@ -209,6 +210,9 @@ Notes:
   `--model openai/gpt-image-1.5` for transparent-background OpenAI PNG output;
   `--openai-background` remains available as an OpenAI-specific alias. Providers
   that do not declare background support report the hint as an ignored override.
+- Use `--quality low|medium|high|auto` for providers that support image quality
+  hints, including OpenAI. OpenAI also accepts `--openai-moderation low|auto` for
+  the provider-specific moderation hint.
 - Use `image providers --json` to verify which bundled image providers are
   discoverable, configured, selected, and which generation/edit capabilities
   each provider exposes.

docs/cli/memory.md

@@ -131,7 +131,7 @@ Dreaming is the background memory consolidation system with three cooperative
 phases: **light** (sort/stage short-term material), **deep** (promote durable
 facts into `MEMORY.md`), and **REM** (reflect and surface themes).
 
-- Enable with `plugins.entries.memory-core.config.dreaming.enabled: true`.
+- Enable with `agents.defaults.memory.extensions.memory-core.dreaming.enabled: true`.
 - Toggle from chat with `/dreaming on|off` (or inspect with `/dreaming status`).
 - Dreaming runs on one managed sweep schedule (`dreaming.frequency`) and executes phases in order: light, REM, deep.
 - Only the deep phase writes durable memory to `MEMORY.md`.
@@ -167,7 +167,7 @@ Example:
 Notes:
 
 - `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
-- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
+- `memory status` includes any extra paths configured via `memory.search.extraPaths`.
 - If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
 - Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
 - Tune scheduled sweep cadence with `dreaming.frequency`. Deep promotion policy is otherwise internal except for `dreaming.phases.deep.maxPromotedSnippetTokens`, which bounds promoted snippet length while keeping provenance visible. Use CLI flags on `memory promote` when you need one-off manual threshold overrides.

docs/cli/policy.md

@@ -398,12 +398,12 @@ allowlist such as `["all"]`.
 
 #### Data Handling
 
-| Policy field                                        | Observed state                                                                       | Use when                                                               |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| `dataHandling.sensitiveLogging.requireRedaction`    | `logging.redactSensitive`                                                            | Set to `true` to reject `logging.redactSensitive: "off"`.              |
-| `dataHandling.telemetry.denyContentCapture`         | `diagnostics.otel.captureContent`                                                    | Set to `true` to reject telemetry content capture.                     |
-| `dataHandling.retention.requireSessionMaintenance`  | `session.maintenance.mode`                                                           | Set to `true` to require effective session maintenance mode `enforce`. |
-| `dataHandling.memory.denySessionTranscriptIndexing` | `memory.qmd.sessions.enabled` and `agents.*.memorySearch.experimental.sessionMemory` | Set to `true` to reject session transcript indexing into memory.       |
+| Policy field                                        | Observed state                                                                                 | Use when                                                               |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `dataHandling.sensitiveLogging.requireRedaction`    | `logging.redactSensitive`                                                                      | Set to `true` to reject `logging.redactSensitive: "off"`.              |
+| `dataHandling.telemetry.denyContentCapture`         | `diagnostics.otel.captureContent`                                                              | Set to `true` to reject telemetry content capture.                     |
+| `dataHandling.retention.requireSessionMaintenance`  | `session.maintenance.mode`                                                                     | Set to `true` to require effective session maintenance mode `enforce`. |
+| `dataHandling.memory.denySessionTranscriptIndexing` | `agents.*.memory.qmd.sessions.enabled` and `agents.*.memory.search.experimental.sessionMemory` | Set to `true` to reject session transcript indexing into memory.       |
 
 #### Secrets
 

docs/cli/status.md

@@ -19,7 +19,7 @@ Notes:
 
 - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
 - Plain `openclaw status` stays on the fast read-only path and marks memory as `not checked` instead of unavailable when it skips memory inspection. Heavy security audit, plugin compatibility, and memory-vector probes are left to `openclaw status --all`, `openclaw status --deep`, `openclaw security audit`, and `openclaw memory status --deep`.
-- `status --json --all` reports memory details from the active memory plugin runtime selected by `plugins.slots.memory`. Custom memory plugins can leave built-in `agents.defaults.memorySearch.enabled` disabled and still report their own files, chunks, vector, and FTS state.
+- `status --json --all` reports memory details from the active memory plugin runtime selected by `plugins.slots.memory`. Custom memory plugins can leave built-in `agents.defaults.memory.search.enabled` disabled and still report their own files, chunks, vector, and FTS state.
 - `--usage` prints normalized provider usage windows as `X% left`.
 - Session status output separates `Execution:` from `Runtime:`. `Execution` is the sandbox path (`direct`, `docker/*`), while `Runtime` tells you whether the session is using `OpenClaw Default`, `OpenAI Codex`, a CLI backend, or an ACP backend such as `codex (acp/acpx)`. See [Agent runtimes](/concepts/agent-runtimes) for the provider/model/runtime distinction.
 - MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.

docs/cli/wiki.md

@@ -32,6 +32,7 @@ Use `openclaw wiki` when you want a compiled knowledge vault with:
 
 ```bash
 openclaw wiki status
+openclaw wiki --agent research status
 openclaw wiki doctor
 openclaw wiki init
 openclaw wiki ingest ./notes/alpha.md
@@ -266,15 +267,16 @@ These require the official `obsidian` CLI on `PATH` when
 
 ## Configuration tie-ins
 
-`openclaw wiki` behavior is shaped by:
+`openclaw wiki` resolves config for the selected `--agent` (or the configured
+default agent) from:
 
-- `plugins.entries.memory-wiki.config.vaultMode`
-- `plugins.entries.memory-wiki.config.search.backend`
-- `plugins.entries.memory-wiki.config.search.corpus`
-- `plugins.entries.memory-wiki.config.bridge.*`
-- `plugins.entries.memory-wiki.config.obsidian.*`
-- `plugins.entries.memory-wiki.config.render.*`
-- `plugins.entries.memory-wiki.config.context.includeCompiledDigestPrompt`
+- `agents.defaults.memory.extensions.memory-wiki.vaultMode`
+- `agents.defaults.memory.extensions.memory-wiki.search.backend`
+- `agents.defaults.memory.extensions.memory-wiki.search.corpus`
+- `agents.defaults.memory.extensions.memory-wiki.bridge.*`
+- `agents.defaults.memory.extensions.memory-wiki.obsidian.*`
+- `agents.defaults.memory.extensions.memory-wiki.render.*`
+- `agents.defaults.memory.extensions.memory-wiki.context.includeCompiledDigestPrompt`
 
 See [Memory Wiki plugin](/plugins/memory-wiki) for the full config model.
 

docs/concepts/active-memory.md

@@ -819,14 +819,14 @@ confirm `config.toolsAllow` names the tools that plugin actually registers.
 
 <AccordionGroup>
   <Accordion title="Embedding provider switched or stopped working">
-    If `memorySearch.provider` is unset, OpenClaw uses OpenAI embeddings. Set
-    `memorySearch.provider` explicitly for local, Ollama, Gemini, Voyage,
+    If `memory.search.provider` is unset, OpenClaw uses OpenAI embeddings. Set
+    `memory.search.provider` explicitly for local, Ollama, Gemini, Voyage,
     Mistral, DeepInfra, Bedrock, GitHub Copilot, or OpenAI-compatible
     embeddings. If the configured provider cannot run, `memory_search` may
     degrade to lexical-only retrieval; runtime failures after a provider is
     already selected do not fall back automatically.
 
-    Set an optional `memorySearch.fallback` only when you want a deliberate
+    Set an optional `memory.search.fallback` only when you want a deliberate
     single fallback. See [Memory Search](/concepts/memory-search) for the full
     list of providers and examples.
 

docs/concepts/dreaming.md

@@ -18,8 +18,10 @@ Dreaming is **opt-in** and disabled by default.
 
 Dreaming keeps two kinds of output:
 
-- **Machine state** in `memory/.dreams/` (recall store, phase signals, ingestion checkpoints, locks).
-- **Human-readable output** in `DREAMS.md` (or existing `dreams.md`) and optional phase report files under `memory/dreaming/<phase>/YYYY-MM-DD.md`.
+- **Agent-private state and artifacts** under
+  `memory/.dreams/agents/<agent-id>/` (recall journals, phase output, reports,
+  and the Dream Diary). Normal memory search does not index this directory.
+- **Shared durable memory** in `MEMORY.md`.
 
 Long-term promotion still writes only to `MEMORY.md`.
 
@@ -52,7 +54,7 @@ These phases are internal implementation details, not separate user-configured "
     - Requires `minScore`, `minRecallCount`, and `minUniqueQueries` to pass.
     - Rehydrates snippets from live daily files before writing, so stale/deleted snippets are skipped.
     - Appends promoted entries to `MEMORY.md`.
-    - Writes a `## Deep Sleep` summary into `DREAMS.md` and optionally writes `memory/dreaming/deep/YYYY-MM-DD.md`.
+    - Writes a `## Deep Sleep` summary into the agent's `DREAMS.md` and optionally writes an agent-private report.
 
   </Accordion>
   <Accordion title="REM phase">
@@ -72,7 +74,12 @@ Dreaming can ingest redacted session transcripts into the dreaming corpus. When
 
 ## Dream Diary
 
-Dreaming also keeps a narrative **Dream Diary** in `DREAMS.md`. After each phase has enough material, `memory-core` runs a best-effort background subagent turn and appends a short diary entry. It uses the default runtime model unless `dreaming.model` is configured. If the configured model is unavailable, Dream Diary retries once with the session default model.
+Dreaming also keeps a narrative **Dream Diary** in
+`memory/.dreams/agents/<agent-id>/DREAMS.md`. After each phase has enough
+material, `memory-core` runs a best-effort background subagent turn and appends
+a short diary entry. It uses the default runtime model unless `dreaming.model`
+is configured. If the configured model is unavailable, Dream Diary retries once
+with the session default model.
 
 <Note>
 This diary is for human reading in the Dreams UI, not a promotion source. Dreaming-generated diary/report artifacts are excluded from short-term promotion. Only grounded memory snippets are eligible to promote into `MEMORY.md`.
@@ -105,7 +112,8 @@ Deep ranking uses six weighted base signals plus phase reinforcement:
 | Consolidation       | 0.10   | Multi-day recurrence strength                     |
 | Conceptual richness | 0.06   | Concept-tag density from snippet/path             |
 
-Light and REM phase hits add a small recency-decayed boost from `memory/.dreams/phase-signals.json`.
+Light and REM phase hits add a small recency-decayed boost from agent-scoped
+dreaming state.
 
 Shadow-trial results can be layered on top of that base score as a review
 signal before any durable write. A helpful trial gives the candidate a small
@@ -136,16 +144,18 @@ harmful verdicts map to `reject`; none of those recommendations writes to
 
 ## Scheduling
 
-When enabled, `memory-core` auto-manages one cron job for a full dreaming sweep. Each sweep runs phases in order: light → REM → deep.
+When enabled, `memory-core` auto-manages one cron job per enabled agent. Each
+sweep runs phases in order: light → REM → deep.
 
-The sweep includes the primary runtime workspace and any configured agent workspaces, deduped by path, so subagent workspace fan-out does not exclude the main agent's `DREAMS.md` and memory state.
+Each cron job runs only that agent's workspace and memory state. Agents that set
+`agents.*.memory.extensions.memory-core.dreaming.enabled: false` receive no job.
 
 Default cadence behavior:
 
-| Setting              | Default       |
-| -------------------- | ------------- |
-| `dreaming.frequency` | `0 3 * * *`   |
-| `dreaming.model`     | default model |
+| Setting                                            | Default       |
+| -------------------------------------------------- | ------------- |
+| `memory.extensions.memory-core.dreaming.frequency` | `0 3 * * *`   |
+| `memory.extensions.memory-core.dreaming.model`     | default model |
 
 ## Quick start
 
@@ -153,12 +163,14 @@ Default cadence behavior:
   <Tab title="Enable dreaming">
     ```json
     {
-      "plugins": {
-        "entries": {
-          "memory-core": {
-            "config": {
-              "dreaming": {
-                "enabled": true
+      "agents": {
+        "defaults": {
+          "memory": {
+            "extensions": {
+              "memory-core": {
+                "dreaming": {
+                  "enabled": true
+                }
               }
             }
           }
@@ -170,14 +182,16 @@ Default cadence behavior:
   <Tab title="Custom sweep cadence">
     ```json
     {
-      "plugins": {
-        "entries": {
-          "memory-core": {
-            "config": {
-              "dreaming": {
-                "enabled": true,
-                "timezone": "America/Los_Angeles",
-                "frequency": "0 */6 * * *"
+      "agents": {
+        "defaults": {
+          "memory": {
+            "extensions": {
+              "memory-core": {
+                "dreaming": {
+                  "enabled": true,
+                  "timezone": "America/Los_Angeles",
+                  "frequency": "0 */6 * * *"
+                }
               }
             }
           }
@@ -233,7 +247,7 @@ Default cadence behavior:
 
 ## Key defaults
 
-All settings live under `plugins.entries.memory-core.config.dreaming`.
+All settings live under `agents.defaults.memory.extensions.memory-core.dreaming`.
 
 <ParamField path="enabled" type="boolean" default="false">
   Enable or disable the dreaming sweep.
@@ -249,7 +263,7 @@ All settings live under `plugins.entries.memory-core.config.dreaming`.
 </ParamField>
 
 <Warning>
-`dreaming.model` requires `plugins.entries.memory-core.subagent.allowModelOverride: true`. To restrict it, also set `plugins.entries.memory-core.subagent.allowedModels`. Trust or allowlist failures stay visible instead of falling back silently; the retry only covers model-unavailable errors.
+`memory.extensions.memory-core.dreaming.model` requires `plugins.entries.memory-core.subagent.allowModelOverride: true`. To restrict it, also set `plugins.entries.memory-core.subagent.allowedModels`. Trust or allowlist failures stay visible instead of falling back silently; the retry only covers model-unavailable errors.
 </Warning>
 
 <Note>

docs/concepts/experimental-features.md

@@ -24,7 +24,7 @@ Treat them differently from normal config:
 | Surface                  | Key                                                                                        | Use it when                                                                                                                       | More                                                                                          |
 | ------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | Local model runtime      | `agents.defaults.experimental.localModelLean`, `agents.list[].experimental.localModelLean` | A smaller or stricter local backend chokes on OpenClaw's full default tool surface                                                | [Local Models](/gateway/local-models)                                                         |
-| Memory search            | `agents.defaults.memorySearch.experimental.sessionMemory`                                  | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost                            | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
+| Memory search            | `agents.defaults.memory.search.experimental.sessionMemory`                                 | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost                            | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
 | Codex harness            | `plugins.entries.codex.config.appServer.experimental.sandboxExecServer`                    | You want native Codex app-server 0.132.0 or newer to target an OpenClaw sandbox-backed exec-server instead of disabling Code Mode | [Codex harness reference](/plugins/codex-harness-reference#sandboxed-native-execution)        |
 | Structured planning tool | `tools.experimental.planTool`                                                              | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs                    | [Gateway configuration reference](/gateway/config-tools#toolsexperimental)                    |
 

docs/concepts/memory-builtin.md

@@ -29,8 +29,10 @@ To set a provider explicitly:
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "openai",
+      memory: {
+        search: {
+          provider: "openai",
+        },
       },
     },
   },
@@ -50,11 +52,13 @@ openclaw plugins install @openclaw/llama-cpp-provider
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "local",
-        fallback: "none",
-        local: {
-          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
+      memory: {
+        search: {
+          provider: "local",
+          fallback: "none",
+          local: {
+            modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
+          },
         },
       },
     },
@@ -77,14 +81,15 @@ openclaw plugins install @openclaw/llama-cpp-provider
 | OpenAI-compatible | `openai-compatible` | Generic `/v1/embeddings` endpoint   |
 | Voyage            | `voyage`            |                                     |
 
-Set `memorySearch.provider` to switch away from OpenAI.
+Set `memory.search.provider` to switch away from OpenAI.
 
 ## How indexing works
 
 OpenClaw indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
 80-token overlap) and stores them in a per-agent SQLite database.
 
-- **Index location:** `~/.openclaw/memory/<agentId>.sqlite`
+- **Index location:** the owning agent database at
+  `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`
 - **Storage maintenance:** SQLite WAL sidecars are bounded with periodic and
   shutdown checkpoints.
 - **File watching:** changes to memory files trigger a debounced reindex (1.5s).
@@ -94,7 +99,7 @@ OpenClaw indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
 
 <Info>
 You can also index Markdown files outside the workspace with
-`memorySearch.extraPaths`. See the
+`memory.search.extraPaths`. See the
 [configuration reference](/reference/memory-config#additional-memory-paths).
 </Info>
 
@@ -126,7 +131,7 @@ openclaw memory index --force --agent main
 ```
 
 Both standalone CLI commands and the Gateway use the same `local` provider id.
-Set `memorySearch.provider: "local"` when you want local embeddings.
+Set `memory.search.provider: "local"` when you want local embeddings.
 
 **Stale results?** Run `openclaw memory index --force` to rebuild. The watcher
 may miss changes in rare edge cases.

docs/concepts/memory-qmd.md

@@ -33,8 +33,12 @@ binary, and can index content beyond your workspace memory files.
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+      },
+    },
   },
 }
 ```
@@ -51,7 +55,7 @@ present.
 ## How the sidecar works
 
 - OpenClaw creates collections from your workspace memory files and any
-  configured `memory.qmd.paths`, then runs `qmd update` when the QMD manager is
+  configured `agents.defaults.memory.qmd.paths`, then runs `qmd update` when the QMD manager is
   opened and periodically afterward (default every 5 minutes). These refreshes
   run through QMD subprocesses, not an in-process filesystem crawl. Semantic
   modes also run `qmd embed`.
@@ -63,8 +67,8 @@ present.
   avoids importing the memory runtime or creating the long-lived watcher before
   memory is first used.
 - If you want QMD initialized at gateway start anyway, set
-  `memory.qmd.update.startup` to `idle` or `immediate`. With
-  `memory.qmd.update.onBoot: true`, startup runs the initial refresh. With
+  `agents.defaults.memory.qmd.update.startup` to `idle` or `immediate`. With
+  `agents.defaults.memory.qmd.update.onBoot: true`, startup runs the initial refresh. With
   `onBoot: false`, startup skips that immediate refresh but still opens the
   long-lived manager when update or embed intervals are configured, so QMD can
   own its regular watcher and timers.
@@ -72,7 +76,7 @@ present.
   `vsearch` and `query`). `search` is BM25-only, so OpenClaw skips semantic
   vector readiness probes and embedding maintenance in that mode. If a mode
   fails, OpenClaw retries with `qmd query`.
-- When `searchMode` is `query`, set `memory.qmd.rerank` to `false` to use QMD's
+- When `searchMode` is `query`, set `agents.defaults.memory.qmd.rerank` to `false` to use QMD's
   hybrid query path without the reranker. OpenClaw passes `--no-rerank` to the
   direct QMD CLI path and `rerank: false` to QMD's MCP query tool. This option
   requires QMD 2.1 or newer.
@@ -140,10 +144,14 @@ Point QMD at additional directories to make them searchable:
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
-    qmd: {
-      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+        qmd: {
+          paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
+        },
+      },
     },
   },
 }
@@ -159,10 +167,14 @@ Enable session indexing to recall earlier conversations:
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
-    qmd: {
-      sessions: { enabled: true },
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+        qmd: {
+          sessions: { enabled: true },
+        },
+      },
     },
   },
 }
@@ -174,15 +186,19 @@ collection under `~/.openclaw/agents/<id>/qmd/sessions/`.
 ## Search scope
 
 By default, QMD search results are surfaced in direct and channel sessions
-(not groups). Configure `memory.qmd.scope` to change this:
+(not groups). Configure `agents.defaults.memory.qmd.scope` to change this:
 
 ```json5
 {
-  memory: {
-    qmd: {
-      scope: {
-        default: "deny",
-        rules: [{ action: "allow", match: { chatType: "direct" } }],
+  agents: {
+    defaults: {
+      memory: {
+        qmd: {
+          scope: {
+            default: "deny",
+            rules: [{ action: "allow", match: { chatType: "direct" } }],
+          },
+        },
       },
     },
   },
@@ -194,8 +210,8 @@ chat type so empty results are easier to debug.
 
 ## Citations
 
-When `memory.citations` is `auto` or `on`, search snippets include a
-`Source: <path#line>` footer. Set `memory.citations = "off"` to omit the footer
+When `agents.defaults.memory.citations` is `auto` or `on`, search snippets include a
+`Source: <path#line>` footer. Set `agents.defaults.memory.citations = "off"` to omit the footer
 while still passing the path to the agent internally.
 
 ## When to use
@@ -222,10 +238,14 @@ interactive shell. Pin the binary explicitly:
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
-    qmd: {
-      command: "/absolute/path/to/qmd",
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+        qmd: {
+          command: "/absolute/path/to/qmd",
+        },
+      },
     },
   },
 }
@@ -243,14 +263,14 @@ QMD advertises support for multiple `-c` filters; otherwise it keeps the older
 per-collection fallback for correctness.
 
 **BM25-only QMD still trying to build llama.cpp?** Set
-`memory.qmd.searchMode = "search"`. OpenClaw treats that mode as lexical-only,
+`agents.defaults.memory.qmd.searchMode = "search"`. OpenClaw treats that mode as lexical-only,
 does not run QMD vector status probes or embedding maintenance, and leaves
 semantic readiness checks to `vsearch` or `query` setups.
 
-**Search times out?** Increase `memory.qmd.limits.timeoutMs` (default: 4000ms).
+**Search times out?** Increase `agents.defaults.memory.qmd.limits.timeoutMs` (default: 4000ms).
 Set to `120000` for slower hardware.
 
-**Empty results in group chats?** Check `memory.qmd.scope` -- the default only
+**Empty results in group chats?** Check `agents.defaults.memory.qmd.scope` -- the default only
 allows direct and channel sessions.
 
 **Root memory search suddenly got too broad?** Restart the gateway or wait for
@@ -266,7 +286,7 @@ cycle-safe traversal or explicit exclusion controls.
 
 ## Configuration
 
-For the full config surface (`memory.qmd.*`), search modes, update intervals,
+For the full config surface (`agents.defaults.memory.qmd.*`), search modes, update intervals,
 scope rules, and all other knobs, see the
 [Memory configuration reference](/reference/memory-config).
 

docs/concepts/memory-search.md

@@ -20,8 +20,10 @@ backend, set a provider explicitly:
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "openai", // or "gemini", "local", "ollama", "openai-compatible", etc.
+      memory: {
+        search: {
+          provider: "openai", // or "gemini", "local", "ollama", "openai-compatible", etc.
+        },
       },
     },
   },
@@ -39,8 +41,8 @@ may still require native build approval: `pnpm approve-builds` then
 
 Some OpenAI-compatible embedding endpoints require asymmetric labels such as
 `input_type: "query"` for searches and `input_type: "document"` or `"passage"`
-for indexed chunks. Configure those with `memorySearch.queryInputType` and
-`memorySearch.documentInputType`; see the [Memory configuration reference](/reference/memory-config#provider-specific-config).
+for indexed chunks. Configure those with `memory.search.queryInputType` and
+`memory.search.documentInputType`; see the [Memory configuration reference](/reference/memory-config#provider-specific-config).
 
 ## Supported providers
 
@@ -82,7 +84,7 @@ If only one path is available, the other runs alone. Intentional FTS-only mode
 lexical ranking when embeddings are unavailable.
 
 Explicit non-local embedding providers are different. If you set
-`memorySearch.provider` to a concrete remote-backed provider and that provider
+`memory.search.provider` to a concrete remote-backed provider and that provider
 is unavailable at runtime, `memory_search` reports memory as unavailable instead
 of silently using FTS-only results. This keeps a broken configured semantic
 provider visible. Set `provider: "none"` for deliberate FTS-only recall, or fix
@@ -119,11 +121,13 @@ different daily notes.
 {
   agents: {
     defaults: {
-      memorySearch: {
-        query: {
-          hybrid: {
-            mmr: { enabled: true },
-            temporalDecay: { enabled: true },
+      memory: {
+        search: {
+          query: {
+            hybrid: {
+              mmr: { enabled: true },
+              temporalDecay: { enabled: true },
+            },
           },
         },
       },
@@ -143,7 +147,7 @@ setup.
 
 You can optionally index session transcripts so `memory_search` can recall
 earlier conversations. This is opt-in via
-`memorySearch.experimental.sessionMemory`. See the
+`memory.search.experimental.sessionMemory`. See the
 [configuration reference](/reference/memory-config) for details.
 
 ## Troubleshooting
@@ -156,7 +160,7 @@ earlier conversations. This is opt-in via
 
 **Local embeddings time out?** `ollama`, `lmstudio`, and `local` use a longer
 inline batch timeout by default. If the host is simply slow, set
-`agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` and rerun
+`agents.defaults.memory.search.sync.embeddingBatchTimeoutSeconds` and rerun
 `openclaw memory index --force`.
 
 **CJK text not found?** Rebuild the FTS index with

docs/concepts/memory.md

@@ -145,7 +145,7 @@ an API key for any supported provider.
 
 <Info>
 OpenClaw uses OpenAI embeddings by default. Set
-`agents.defaults.memorySearch.provider` explicitly to use Gemini, Voyage,
+`agents.defaults.memory.search.provider` explicitly to use Gemini, Voyage,
 Mistral, local, Ollama, Bedrock, GitHub Copilot, or OpenAI-compatible
 embeddings.
 </Info>
@@ -238,9 +238,9 @@ For phase behavior, scoring signals, and Dream Diary details, see
 
 The dreaming system now has two closely related review lanes:
 
-- **Live dreaming** works from the short-term dreaming store under
-  `memory/.dreams/` and is what the normal deep phase uses when deciding what
-  can graduate into `MEMORY.md`.
+- **Live dreaming** works from an agent-scoped short-term dreaming store under
+  `memory/.dreams/agents/<agent-id>/` and is what the normal deep phase uses
+  when deciding what can graduate into shared `MEMORY.md`.
 - **Grounded backfill** reads historical `memory/YYYY-MM-DD.md` notes as
   standalone day files and writes structured review output into `DREAMS.md`.
 

docs/concepts/model-providers.md

@@ -278,51 +278,28 @@ messages and normalizes `stats.cached` into `cacheRead`; legacy
 - Example models: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6`
 - CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
 
-### Kilo Gateway
-
-- Provider: `kilocode`
-- Auth: `KILOCODE_API_KEY`
-- Example model: `kilocode/kilo/auto`
-- CLI: `openclaw onboard --auth-choice kilocode-api-key`
-- Base URL: `https://api.kilo.ai/api/gateway/`
-- Static fallback catalog ships `kilocode/kilo/auto`; live `https://api.kilo.ai/api/gateway/models` discovery can expand the runtime catalog further.
-- Exact upstream routing behind `kilocode/kilo/auto` is owned by Kilo Gateway, not hard-coded in OpenClaw.
-
-See [/providers/kilocode](/providers/kilocode) for setup details.
-
 ### Other bundled provider plugins
 
-| Provider                                | Id                               | Auth env                                                     | Example model                                              |
-| --------------------------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
-| BytePlus                                | `byteplus` / `byteplus-plan`     | `BYTEPLUS_API_KEY`                                           | `byteplus-plan/ark-code-latest`                            |
-| Cerebras                                | `cerebras`                       | `CEREBRAS_API_KEY`                                           | `cerebras/zai-glm-4.7`                                     |
-| Cohere                                  | `cohere`                         | `COHERE_API_KEY`                                             | `cohere/command-a-03-2025`                                 |
-| Cloudflare AI Gateway                   | `cloudflare-ai-gateway`          | `CLOUDFLARE_AI_GATEWAY_API_KEY`                              | -                                                          |
-| DeepInfra                               | `deepinfra`                      | `DEEPINFRA_API_KEY`                                          | `deepinfra/deepseek-ai/DeepSeek-V4-Flash`                  |
-| DeepSeek                                | `deepseek`                       | `DEEPSEEK_API_KEY`                                           | `deepseek/deepseek-v4-flash`                               |
-| GitHub Copilot                          | `github-copilot`                 | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`         | -                                                          |
-| GMI Cloud                               | `gmi`                            | `GMI_API_KEY`                                                | `gmi/google/gemini-3.1-flash-lite`                         |
-| Groq                                    | `groq`                           | `GROQ_API_KEY`                                               | -                                                          |
-| Hugging Face Inference                  | `huggingface`                    | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`                        | `huggingface/deepseek-ai/DeepSeek-R1`                      |
-| Kilo Gateway                            | `kilocode`                       | `KILOCODE_API_KEY`                                           | `kilocode/kilo/auto`                                       |
-| Kimi Coding                             | `kimi`                           | `KIMI_API_KEY` or `KIMICODE_API_KEY`                         | `kimi/kimi-for-coding`                                     |
-| MiniMax                                 | `minimax` / `minimax-portal`     | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`                    | `minimax/MiniMax-M3`                                       |
-| Mistral                                 | `mistral`                        | `MISTRAL_API_KEY`                                            | `mistral/mistral-large-latest`                             |
-| Moonshot                                | `moonshot`                       | `MOONSHOT_API_KEY`                                           | `moonshot/kimi-k2.6`                                       |
-| NVIDIA                                  | `nvidia`                         | `NVIDIA_API_KEY`                                             | `nvidia/nvidia/nemotron-3-ultra-550b-a55b`                 |
-| NovitaAI                                | `novita`                         | `NOVITA_API_KEY`                                             | `novita/deepseek/deepseek-v3-0324`                         |
-| [Ollama Cloud](/providers/ollama-cloud) | `ollama-cloud`                   | `OLLAMA_API_KEY`                                             | `ollama-cloud/kimi-k2.6`                                   |
-| OpenRouter                              | `openrouter`                     | OpenRouter OAuth or `OPENROUTER_API_KEY`                     | `openrouter/auto`                                          |
-| Qianfan                                 | `qianfan`                        | `QIANFAN_API_KEY`                                            | `qianfan/deepseek-v3.2`                                    |
-| Qwen Cloud                              | `qwen`                           | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus`                                        |
-| [Qwen OAuth](/providers/qwen-oauth)     | `qwen-oauth`                     | `QWEN_API_KEY`                                               | `qwen-oauth/qwen3.5-plus`                                  |
-| StepFun                                 | `stepfun` / `stepfun-plan`       | `STEPFUN_API_KEY`                                            | `stepfun/step-3.5-flash`                                   |
-| Together                                | `together`                       | `TOGETHER_API_KEY`                                           | `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`         |
-| Venice                                  | `venice`                         | `VENICE_API_KEY`                                             | -                                                          |
-| Vercel AI Gateway                       | `vercel-ai-gateway`              | `AI_GATEWAY_API_KEY`                                         | `vercel-ai-gateway/anthropic/claude-opus-4.6`              |
-| Volcano Engine (Doubao)                 | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY`                                     | `volcengine-plan/ark-code-latest`                          |
-| xAI                                     | `xai`                            | SuperGrok/X Premium OAuth or `XAI_API_KEY`                   | `xai/grok-4.3`                                             |
-| Xiaomi                                  | `xiaomi` / `xiaomi-token-plan`   | `XIAOMI_API_KEY` / `XIAOMI_TOKEN_PLAN_API_KEY`               | `xiaomi/mimo-v2-flash` / `xiaomi-token-plan/mimo-v2.5-pro` |
+| Provider                                | Id                               | Auth env                                             | Example model                                              |
+| --------------------------------------- | -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| BytePlus                                | `byteplus` / `byteplus-plan`     | `BYTEPLUS_API_KEY`                                   | `byteplus-plan/ark-code-latest`                            |
+| Cohere                                  | `cohere`                         | `COHERE_API_KEY`                                     | `cohere/command-a-03-2025`                                 |
+| GitHub Copilot                          | `github-copilot`                 | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | -                                                          |
+| Hugging Face Inference                  | `huggingface`                    | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`                | `huggingface/deepseek-ai/DeepSeek-R1`                      |
+| MiniMax                                 | `minimax` / `minimax-portal`     | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`            | `minimax/MiniMax-M3`                                       |
+| Mistral                                 | `mistral`                        | `MISTRAL_API_KEY`                                    | `mistral/mistral-large-latest`                             |
+| Moonshot                                | `moonshot`                       | `MOONSHOT_API_KEY`                                   | `moonshot/kimi-k2.6`                                       |
+| NVIDIA                                  | `nvidia`                         | `NVIDIA_API_KEY`                                     | `nvidia/nvidia/nemotron-3-ultra-550b-a55b`                 |
+| NovitaAI                                | `novita`                         | `NOVITA_API_KEY`                                     | `novita/deepseek/deepseek-v3-0324`                         |
+| [Ollama Cloud](/providers/ollama-cloud) | `ollama-cloud`                   | `OLLAMA_API_KEY`                                     | `ollama-cloud/kimi-k2.6`                                   |
+| OpenRouter                              | `openrouter`                     | OpenRouter OAuth or `OPENROUTER_API_KEY`             | `openrouter/auto`                                          |
+| [Qwen OAuth](/providers/qwen-oauth)     | `qwen-oauth`                     | `QWEN_API_KEY`                                       | `qwen-oauth/qwen3.5-plus`                                  |
+| Together                                | `together`                       | `TOGETHER_API_KEY`                                   | `together/meta-llama/Llama-3.3-70B-Instruct-Turbo`         |
+| Venice                                  | `venice`                         | `VENICE_API_KEY`                                     | -                                                          |
+| Vercel AI Gateway                       | `vercel-ai-gateway`              | `AI_GATEWAY_API_KEY`                                 | `vercel-ai-gateway/anthropic/claude-opus-4.6`              |
+| Volcano Engine (Doubao)                 | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY`                             | `volcengine-plan/ark-code-latest`                          |
+| xAI                                     | `xai`                            | SuperGrok/X Premium OAuth or `XAI_API_KEY`           | `xai/grok-4.3`                                             |
+| Xiaomi                                  | `xiaomi` / `xiaomi-token-plan`   | `XIAOMI_API_KEY` / `XIAOMI_TOKEN_PLAN_API_KEY`       | `xiaomi/mimo-v2-flash` / `xiaomi-token-plan/mimo-v2.5-pro` |
 
 #### Quirks worth knowing
 
@@ -342,9 +319,6 @@ See [/providers/kilocode](/providers/kilocode) for setup details.
   <Accordion title="xAI">
     Uses the xAI Responses path. The recommended path is SuperGrok/X Premium OAuth; API keys still work via `XAI_API_KEY` or plugin config, and Grok `web_search` reuses the same auth profile before API-key fallback. `grok-4.3` is the bundled default chat model, and `grok-build-0.1` is selectable for build/coding-focused work. `/fast` or `params.fastMode: true` rewrites `grok-3`, `grok-3-mini`, `grok-4`, and `grok-4-0709` to their `*-fast` variants. `tool_stream` defaults on; disable via `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
   </Accordion>
-  <Accordion title="Cerebras">
-    Ships as the bundled `cerebras` provider plugin. GLM uses `zai-glm-4.7`; OpenAI-compatible base URL is `https://api.cerebras.ai/v1`.
-  </Accordion>
 </AccordionGroup>
 
 ## Providers via `models.providers` (custom/base URL)

docs/concepts/multi-agent.md

@@ -130,16 +130,18 @@ This lets **multiple people** share one Gateway server while keeping their AI "b
 
 ## Cross-agent QMD memory search
 
-If one agent should search another agent's QMD session transcripts, add extra collections under `agents.list[].memorySearch.qmd.extraCollections`. Use `agents.defaults.memorySearch.qmd.extraCollections` only when every agent should inherit the same shared transcript collections.
+If one agent should search another agent's QMD session transcripts, add extra collections under `agents.list[].memory.search.qmd.extraCollections`. Use `agents.defaults.memory.search.qmd.extraCollections` only when every agent should inherit the same shared transcript collections.
 
 ```json5
 {
   agents: {
     defaults: {
       workspace: "~/workspaces/main",
-      memorySearch: {
-        qmd: {
-          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
+      memory: {
+        search: {
+          qmd: {
+            extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
+          },
         },
       },
     },
@@ -147,9 +149,11 @@ If one agent should search another agent's QMD session transcripts, add extra co
       {
         id: "main",
         workspace: "~/workspaces/main",
-        memorySearch: {
-          qmd: {
-            extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
+        memory: {
+          search: {
+            qmd: {
+              extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
+            },
           },
         },
       },

docs/docs.json

@@ -1387,10 +1387,7 @@
                   "clawhub/http-api",
                   "clawhub/acceptable-usage",
                   "clawhub/moderation",
-                  "clawhub/security",
-                  "clawhub/security-audits",
-                  "clawhub/content-rights",
-                  "clawhub/plugin-validation-fixes"
+                  "clawhub/security-audits"
                 ]
               }
             ]

docs/gateway/config-agents.md

@@ -189,7 +189,7 @@ knob.
   the compact skills list injected into the system prompt.
 - `agents.defaults.contextLimits.*`:
   bounded runtime excerpts and injected runtime-owned blocks.
-- `memory.qmd.limits.*`:
+- `agents.defaults.memory.qmd.limits.*`:
   indexed memory-search snippet and injection sizing.
 
 Use the matching per-agent override only when one agent needs a different
@@ -438,7 +438,7 @@ Time format in system prompt. Default: `auto` (OS preference).
   - Typical values: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, or `qwen/wan2.7-r2v`.
   - If omitted, `video_generate` can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered video-generation providers in provider-id order.
   - If you select a provider/model directly, configure the matching provider auth/API key too.
-  - The bundled Qwen video-generation provider supports up to 1 output video, 1 input image, 4 input videos, 10 seconds duration, and provider-level `size`, `aspectRatio`, `resolution`, `audio`, and `watermark` options.
+  - The official Qwen video-generation plugin supports up to 1 output video, 1 input image, 4 input videos, 10 seconds duration, and provider-level `size`, `aspectRatio`, `resolution`, `audio`, and `watermark` options.
 - `pdfModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the `pdf` tool for model routing.
   - If omitted, the PDF tool falls back to `imageModel`, then to the resolved session/default model.

docs/gateway/config-tools.md

@@ -590,7 +590,7 @@ Interactive custom-provider onboarding infers image input for common vision mode
 
 <AccordionGroup>
   <Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
-    The bundled `cerebras` provider plugin can configure this via `openclaw onboard --auth-choice cerebras-api-key`. Use explicit provider config only when overriding defaults.
+    The official external `cerebras` provider plugin can configure this via `openclaw onboard --auth-choice cerebras-api-key`. Use explicit provider config only when overriding defaults.
 
     ```json5
     {

docs/gateway/configuration-examples.md

@@ -281,13 +281,15 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
         prompt: "HEARTBEAT",
         ackMaxChars: 300,
       },
-      memorySearch: {
-        provider: "gemini",
-        model: "gemini-embedding-001",
-        remote: {
-          apiKey: "${GEMINI_API_KEY}",
+      memory: {
+        search: {
+          provider: "gemini",
+          model: "gemini-embedding-001",
+          remote: {
+            apiKey: "${GEMINI_API_KEY}",
+          },
+          extraPaths: ["../team-docs", "/srv/shared-notes"],
         },
-        extraPaths: ["../team-docs", "/srv/shared-notes"],
       },
       sandbox: {
         mode: "non-main",

docs/gateway/configuration-reference.md

@@ -23,7 +23,7 @@ for the broader field map, defaults, and links to subsystem references.
 
 Dedicated deep references:
 
-- [Memory configuration reference](/reference/memory-config) for `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, and dreaming config under `plugins.entries.memory-core.config.dreaming`
+- [Memory configuration reference](/reference/memory-config) for `agents.defaults.memory.search.*`, `agents.defaults.memory.qmd.*`, `agents.defaults.memory.citations`, and dreaming config under `agents.defaults.memory.extensions.memory-core.dreaming`
 - [Slash commands](/tools/slash-commands) for the current built-in + bundled command catalog
 - owning channel/plugin pages for channel-specific command surfaces
 
@@ -340,7 +340,7 @@ session establishment, not on every turn; use `/new`, `/reset`, or a gateway
 restart after changing native plugin config.
 
 - `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch provider settings.
-  - `apiKey`: Firecrawl API key (accepts SecretRef). Falls back to `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey`, or `FIRECRAWL_API_KEY` env var.
+  - `apiKey`: Optional Firecrawl API key for higher limits (accepts SecretRef). Falls back to `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey`, or `FIRECRAWL_API_KEY` env var.
   - `baseUrl`: Firecrawl API base URL (default: `https://api.firecrawl.dev`; self-hosted overrides must target private/internal endpoints).
   - `onlyMainContent`: extract only the main content from pages (default: `true`).
   - `maxAgeMs`: maximum cache age in milliseconds (default: `172800000` / 2 days).
@@ -348,17 +348,17 @@ restart after changing native plugin config.
 - `plugins.entries.xai.config.xSearch`: xAI X Search (Grok web search) settings.
   - `enabled`: enable the X Search provider.
   - `model`: Grok model to use for search (e.g. `"grok-4-1-fast"`).
-- `plugins.entries.memory-core.config.dreaming`: memory dreaming settings. See [Dreaming](/concepts/dreaming) for phases and thresholds.
+- `agents.defaults.memory.extensions.memory-core.dreaming`: memory dreaming settings. See [Dreaming](/concepts/dreaming) for phases and thresholds.
   - `enabled`: master dreaming switch (default `false`).
   - `frequency`: cron cadence for each full dreaming sweep (`"0 3 * * *"` by default).
   - `model`: optional Dream Diary subagent model override. Requires `plugins.entries.memory-core.subagent.allowModelOverride: true`; pair with `allowedModels` to restrict targets. Model-unavailable errors retry once with the session default model; trust or allowlist failures do not fall back silently.
   - phase policy and thresholds are implementation details (not user-facing config keys).
 - Full memory config lives in [Memory configuration reference](/reference/memory-config):
-  - `agents.defaults.memorySearch.*`
-  - `memory.backend`
-  - `memory.citations`
-  - `memory.qmd.*`
-  - `plugins.entries.memory-core.config.dreaming`
+  - `agents.defaults.memory.search.*`
+  - `agents.defaults.memory.backend`
+  - `agents.defaults.memory.citations`
+  - `agents.defaults.memory.qmd.*`
+  - `agents.defaults.memory.extensions.memory-core.dreaming`
 - Enabled Claude bundle plugins can also contribute embedded OpenClaw defaults from `settings.json`; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches.
 - `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins.
 - `plugins.slots.contextEngine`: pick the active context engine plugin id; defaults to `"legacy"` unless you install and select another engine.

docs/gateway/doctor.md

@@ -519,7 +519,7 @@ That stages grounded durable candidates into the short-term dreaming store while
     - **QMD backend**: probes whether the `qmd` binary is available and startable. If not, prints fix guidance including the npm package and a manual binary path option.
     - **Explicit local provider**: checks for a local model file or a recognized remote/downloadable model URL. If missing, suggests switching to a remote provider.
     - **Explicit remote provider** (`openai`, `voyage`, etc.): verifies an API key is present in the environment or auth store. Prints actionable fix hints if missing.
-    - **Legacy auto provider**: treats `memorySearch.provider: "auto"` as OpenAI, checks OpenAI readiness, and `doctor --fix` rewrites it to `provider: "openai"`.
+    - **Legacy auto provider**: treats `memory.search.provider: "auto"` as OpenAI, checks OpenAI readiness, and `doctor --fix` rewrites it to `provider: "openai"`.
 
     When a cached gateway probe result is available (gateway was healthy at the time of the check), doctor cross-references its result with the CLI-visible config and notes any discrepancy. Doctor does not start a fresh embedding ping on the default path; use the deep memory status command when you want a live provider check.
 

docs/help/faq.md

@@ -549,14 +549,14 @@ lives on the [First-run FAQ](/help/faq-first-run).
     still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`).
 
     If you don't set a provider explicitly, OpenClaw uses OpenAI embeddings. Legacy
-    configs that still say `memorySearch.provider = "auto"` resolve to OpenAI too.
+    configs that still say `memory.search.provider = "auto"` resolve to OpenAI too.
     If no OpenAI API key is available, semantic memory search stays unavailable
     until you configure a key or choose another provider explicitly.
 
-    If you'd rather stay local, set `memorySearch.provider = "local"` (and optionally
-    `memorySearch.fallback = "none"`). If you want Gemini embeddings, set
-    `memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or
-    `memorySearch.remote.apiKey`). We support **OpenAI, OpenAI-compatible, Gemini,
+    If you'd rather stay local, set `memory.search.provider = "local"` (and optionally
+    `memory.search.fallback = "none"`). If you want Gemini embeddings, set
+    `memory.search.provider = "gemini"` and provide `GEMINI_API_KEY` (or
+    `memory.search.remote.apiKey`). We support **OpenAI, OpenAI-compatible, Gemini,
     Voyage, Mistral, Bedrock, Ollama, LM Studio, GitHub Copilot, DeepInfra, or local**
     embedding models - see [Memory](/concepts/memory) for the setup details.
 
@@ -857,7 +857,7 @@ lives on the [First-run FAQ](/help/faq-first-run).
 
     - If you use allowlists, add `web_search`/`web_fetch`/`x_search` or `group:web`.
     - `web_fetch` is enabled by default (unless explicitly disabled).
-    - If `tools.web.fetch.provider` is omitted, OpenClaw auto-detects the first ready fetch fallback provider from available credentials. Today the bundled provider is Firecrawl.
+    - If `tools.web.fetch.provider` is omitted, OpenClaw auto-detects the first ready fetch fallback provider from available credentials. The official Firecrawl plugin provides that fallback.
     - Daemons read env vars from `~/.openclaw/.env` (or the service environment).
 
     Docs: [Web tools](/tools/web).

docs/nodes/audio.md

@@ -28,7 +28,7 @@ OpenClaw auto-detects in this order and stops at the first working option:
    - `whisper` (Python CLI; downloads models automatically)
 3. **Provider auth**
    - Configured `models.providers.*` entries that support audio are tried first
-   - Bundled fallback order: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
+   - Provider fallback order: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
 
 As of 2026-05-22, Gemini CLI auto-detect is no longer supported for media understanding. Google is transitioning Gemini CLI users to Antigravity CLI; audio should use local or provider transcription, while image/video CLI fallback should move to Antigravity CLI (`agy`).
 

docs/plugins/copilot.md

@@ -179,8 +179,7 @@ The harness reads its config from per-attempt input
   registered with `overridesBuiltInTool: true` and
   `skipPermission: true` so 100% of tool calls flow through OpenClaw's
   wrapped `execute()`. See [Permissions and ask_user](#permissions-and-ask_user).
-- `enableSessionTelemetry` — opt-in OpenTelemetry routing via
-  `telemetry-bridge.ts`.
+- `enableSessionTelemetry` — optional SDK session telemetry flag.
 
 Nothing in the rest of OpenClaw needs to know about these fields. Other
 plugins, channels, and core code only see the standard
@@ -267,9 +266,7 @@ real Copilot CLI or touch the host fs.
   decisions from the initial prompt rather than asking clarifying
   questions mid-turn. A follow-up will port the codex pattern at
   `extensions/codex/src/app-server/user-input-bridge.ts` to route SDK
-  `UserInputRequest`s through the OpenClaw channel/TUI prompt path; the
-  dormant scaffolding in `extensions/copilot/src/user-input-bridge.ts`
-  is the surface that follow-up will wire.
+  `UserInputRequest`s through the OpenClaw channel/TUI prompt path.
 
 ## Permissions and ask_user
 

docs/plugins/llama-cpp.md

@@ -2,7 +2,7 @@
 summary: "Install the official llama.cpp provider for local GGUF memory embeddings"
 read_when:
   - You want memory search embeddings from a local GGUF model
-  - You are configuring memorySearch.provider = "local"
+  - You are configuring memory.search.provider = "local"
   - You need the OpenClaw plugin that owns the node-llama-cpp runtime
 title: "llama.cpp Provider"
 sidebarTitle: "llama.cpp Provider"
@@ -10,7 +10,7 @@ sidebarTitle: "llama.cpp Provider"
 
 `llama-cpp` is the official external provider plugin for local GGUF embeddings.
 It owns the `node-llama-cpp` runtime dependency used by
-`memorySearch.provider: "local"`.
+`memory.search.provider: "local"`.
 
 Install it before using local memory embeddings:
 
@@ -30,10 +30,12 @@ Set the memory search provider to `local`:
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "local",
-        local: {
-          modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
+      memory: {
+        search: {
+          provider: "local",
+          local: {
+            modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
+          },
         },
       },
     },

docs/plugins/memory-wiki.md

@@ -397,50 +397,57 @@ engines or legacy prompt assembly that explicitly consume memory supplements.
 
 ## Configuration
 
-Put config under `plugins.entries.memory-wiki.config`:
+Put config under `agents.defaults.memory.extensions.memory-wiki`. Agent entries
+can override the same object at `agents.list[].memory.extensions.memory-wiki`.
+Enable the plugin once under `plugins.entries`; its settings remain agent-scoped.
 
 ```json5
 {
   plugins: {
     entries: {
-      "memory-wiki": {
-        enabled: true,
-        config: {
-          vaultMode: "isolated",
-          vault: {
-            path: "~/.openclaw/wiki/main",
-            renderMode: "obsidian",
-          },
-          obsidian: {
-            enabled: true,
-            useOfficialCli: true,
-            vaultName: "OpenClaw Wiki",
-            openAfterWrites: false,
-          },
-          bridge: {
-            enabled: false,
-            readMemoryArtifacts: true,
-            indexDreamReports: true,
-            indexDailyNotes: true,
-            indexMemoryRoot: true,
-            followMemoryEvents: true,
-          },
-          ingest: {
-            autoCompile: true,
-            maxConcurrentJobs: 1,
-            allowUrlIngest: true,
-          },
-          search: {
-            backend: "shared",
-            corpus: "wiki",
-          },
-          context: {
-            includeCompiledDigestPrompt: false,
-          },
-          render: {
-            preserveHumanBlocks: true,
-            createBacklinks: true,
-            createDashboards: true,
+      "memory-wiki": { enabled: true },
+    },
+  },
+  agents: {
+    defaults: {
+      memory: {
+        extensions: {
+          "memory-wiki": {
+            vaultMode: "isolated",
+            vault: {
+              renderMode: "obsidian",
+            },
+            obsidian: {
+              enabled: true,
+              useOfficialCli: true,
+              vaultName: "OpenClaw Wiki",
+              openAfterWrites: false,
+            },
+            bridge: {
+              enabled: false,
+              readMemoryArtifacts: true,
+              indexDreamReports: true,
+              indexDailyNotes: true,
+              indexMemoryRoot: true,
+              followMemoryEvents: true,
+            },
+            ingest: {
+              autoCompile: true,
+              maxConcurrentJobs: 1,
+              allowUrlIngest: true,
+            },
+            search: {
+              backend: "shared",
+              corpus: "wiki",
+            },
+            context: {
+              includeCompiledDigestPrompt: false,
+            },
+            render: {
+              preserveHumanBlocks: true,
+              createBacklinks: true,
+              createDashboards: true,
+            },
           },
         },
       },
@@ -468,29 +475,33 @@ knowledge layer:
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
-  },
   plugins: {
     entries: {
-      "memory-wiki": {
-        enabled: true,
-        config: {
-          vaultMode: "bridge",
-          bridge: {
-            enabled: true,
-            readMemoryArtifacts: true,
-            indexDreamReports: true,
-            indexDailyNotes: true,
-            indexMemoryRoot: true,
-            followMemoryEvents: true,
-          },
-          search: {
-            backend: "shared",
-            corpus: "all",
-          },
-          context: {
-            includeCompiledDigestPrompt: false,
+      "memory-wiki": { enabled: true },
+    },
+  },
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+        extensions: {
+          "memory-wiki": {
+            vaultMode: "bridge",
+            bridge: {
+              enabled: true,
+              readMemoryArtifacts: true,
+              indexDreamReports: true,
+              indexDailyNotes: true,
+              indexMemoryRoot: true,
+              followMemoryEvents: true,
+            },
+            search: {
+              backend: "shared",
+              corpus: "all",
+            },
+            context: {
+              includeCompiledDigestPrompt: false,
+            },
           },
         },
       },

docs/plugins/plugin-inventory.md

@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Core npm package
 
-91 plugins
+72 plugins
 
 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.
 
@@ -59,8 +59,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[anthropic](/plugins/reference/anthropic)** (`@openclaw/anthropic-provider`) - included in OpenClaw. Adds Anthropic model provider support to OpenClaw.
 
-- **[arcee](/plugins/reference/arcee)** (`@openclaw/arcee-provider`) - included in OpenClaw. Adds Arcee model provider support to OpenClaw.
-
 - **[azure-speech](/plugins/reference/azure-speech)** (`@openclaw/azure-speech`) - included in OpenClaw. Azure AI Speech text-to-speech (MP3, native Ogg/Opus voice notes, PCM telephony).
 
 - **[bonjour](/plugins/reference/bonjour)** (`@openclaw/bonjour`) - included in OpenClaw. Advertise the local OpenClaw gateway over Bonjour/mDNS.
@@ -71,17 +69,11 @@ Each entry lists the package, distribution route, and description.
 
 - **[canvas](/plugins/reference/canvas)** (`@openclaw/canvas-plugin`) - included in OpenClaw. Experimental Canvas control and A2UI rendering surfaces for paired nodes.
 
-- **[cerebras](/plugins/reference/cerebras)** (`@openclaw/cerebras-provider`) - included in OpenClaw. Adds Cerebras model provider support to OpenClaw.
-
-- **[chutes](/plugins/reference/chutes)** (`@openclaw/chutes-provider`) - included in OpenClaw. Adds Chutes model provider support to OpenClaw.
-
 - **[clickclack](/plugins/reference/clickclack)** (`@openclaw/clickclack`) - included in OpenClaw. Adds the Clickclack channel surface for sending and receiving OpenClaw messages.
 
-- **[cloudflare-ai-gateway](/plugins/reference/cloudflare-ai-gateway)** (`@openclaw/cloudflare-ai-gateway-provider`) - included in OpenClaw. Adds Cloudflare AI Gateway model provider support to OpenClaw.
-
 - **[codex-supervisor](/plugins/reference/codex-supervisor)** (`@openclaw/codex-supervisor`) - included in OpenClaw. Supervise Codex app-server sessions from OpenClaw.
 
-- **[cohere](/plugins/reference/cohere)** (`@openclaw/cohere-provider`) - included in OpenClaw. Adds Cohere model provider support to OpenClaw.
+- **[cohere](/plugins/reference/cohere)** (`@openclaw/cohere-provider`) - included in OpenClaw; npm; ClawHub: `clawhub:@openclaw/cohere-provider`. OpenClaw Cohere provider plugin.
 
 - **[comfy](/plugins/reference/comfy)** (`@openclaw/comfy-provider`) - included in OpenClaw. Adds ComfyUI model provider support to OpenClaw.
 
@@ -89,48 +81,28 @@ Each entry lists the package, distribution route, and description.
 
 - **[deepgram](/plugins/reference/deepgram)** (`@openclaw/deepgram-provider`) - included in OpenClaw. Adds media understanding provider support. Adds realtime transcription provider support.
 
-- **[deepinfra](/plugins/reference/deepinfra)** (`@openclaw/deepinfra-provider`) - included in OpenClaw. Adds DeepInfra model provider support to OpenClaw.
-
-- **[deepseek](/plugins/reference/deepseek)** (`@openclaw/deepseek-provider`) - included in OpenClaw. Adds DeepSeek model provider support to OpenClaw.
-
 - **[document-extract](/plugins/reference/document-extract)** (`@openclaw/document-extract-plugin`) - included in OpenClaw. Extract text and fallback page images from local document attachments.
 
 - **[duckduckgo](/plugins/reference/duckduckgo)** (`@openclaw/duckduckgo-plugin`) - included in OpenClaw. Adds web search provider support.
 
 - **[elevenlabs](/plugins/reference/elevenlabs)** (`@openclaw/elevenlabs-speech`) - included in OpenClaw. Adds media understanding provider support. Adds realtime transcription provider support. Adds text-to-speech provider support.
 
-- **[exa](/plugins/reference/exa)** (`@openclaw/exa-plugin`) - included in OpenClaw. Adds web search provider support.
-
 - **[fal](/plugins/reference/fal)** (`@openclaw/fal-provider`) - included in OpenClaw. Adds fal model provider support to OpenClaw.
 
 - **[file-transfer](/plugins/reference/file-transfer)** (`@openclaw/file-transfer`) - included in OpenClaw. Fetch, list, and write files on paired nodes via dedicated node commands. Bypasses bash stdout truncation by using base64 over node.invoke for binaries up to 16 MB.
 
-- **[firecrawl](/plugins/reference/firecrawl)** (`@openclaw/firecrawl-plugin`) - included in OpenClaw. Adds agent-callable tools. Adds web fetch provider support. Adds web search provider support.
-
 - **[fireworks](/plugins/reference/fireworks)** (`@openclaw/fireworks-provider`) - included in OpenClaw. Adds Fireworks model provider support to OpenClaw.
 
 - **[github-copilot](/plugins/reference/github-copilot)** (`@openclaw/github-copilot-provider`) - included in OpenClaw. Adds GitHub Copilot model provider support to OpenClaw.
 
-- **[gmi](/plugins/reference/gmi)** (`@openclaw/gmi-provider`) - included in OpenClaw. Adds Gmi, Gmi Cloud, Gmicloud model provider support to OpenClaw.
-
 - **[google](/plugins/reference/google)** (`@openclaw/google-plugin`) - included in OpenClaw. Adds Google, Google Gemini CLI, Google Vertex model provider support to OpenClaw.
 
-- **[gradium](/plugins/reference/gradium)** (`@openclaw/gradium-speech`) - included in OpenClaw. Adds text-to-speech provider support.
-
-- **[groq](/plugins/reference/groq)** (`@openclaw/groq-provider`) - included in OpenClaw. Adds Groq model provider support to OpenClaw.
-
 - **[huggingface](/plugins/reference/huggingface)** (`@openclaw/huggingface-provider`) - included in OpenClaw. Adds Hugging Face model provider support to OpenClaw.
 
 - **[imessage](/plugins/reference/imessage)** (`@openclaw/imessage`) - included in OpenClaw. Adds the iMessage channel surface for sending and receiving OpenClaw messages.
 
-- **[inworld](/plugins/reference/inworld)** (`@openclaw/inworld-speech`) - included in OpenClaw. Inworld streaming text-to-speech (MP3, OGG_OPUS, PCM telephony).
-
 - **[irc](/plugins/reference/irc)** (`@openclaw/irc`) - included in OpenClaw. Adds the IRC channel surface for sending and receiving OpenClaw messages.
 
-- **[kilocode](/plugins/reference/kilocode)** (`@openclaw/kilocode-provider`) - included in OpenClaw. Adds Kilocode model provider support to OpenClaw.
-
-- **[kimi](/plugins/reference/kimi)** (`@openclaw/kimi-provider`) - included in OpenClaw. Adds Kimi, Kimi Coding model provider support to OpenClaw.
-
 - **[litellm](/plugins/reference/litellm)** (`@openclaw/litellm-provider`) - included in OpenClaw. Adds LiteLLM model provider support to OpenClaw.
 
 - **[llm-task](/plugins/reference/llm-task)** (`@openclaw/llm-task`) - included in OpenClaw. Generic JSON-only LLM tool for structured tasks callable from workflows.
@@ -175,16 +147,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[openrouter](/plugins/reference/openrouter)** (`@openclaw/openrouter-provider`) - included in OpenClaw. Adds OpenRouter model provider support to OpenClaw.
 
-- **[parallel](/tools/parallel-search)** (`@openclaw/parallel-plugin`) - included in OpenClaw. Adds web search provider support.
-
-- **[perplexity](/plugins/reference/perplexity)** (`@openclaw/perplexity-plugin`) - included in OpenClaw. Adds web search provider support.
-
 - **[policy](/plugins/reference/policy)** (`@openclaw/policy`) - included in OpenClaw. Adds policy-backed doctor checks for workspace conformance.
 
-- **[qianfan](/plugins/reference/qianfan)** (`@openclaw/qianfan-provider`) - included in OpenClaw. Adds Qianfan model provider support to OpenClaw.
-
-- **[qwen](/plugins/reference/qwen)** (`@openclaw/qwen-provider`) - included in OpenClaw. Adds Qwen, Qwen Cloud, Model Studio, DashScope, Qwen Oauth, Qwen Portal, Qwen CLI model provider support to OpenClaw.
-
 - **[runway](/plugins/reference/runway)** (`@openclaw/runway-provider`) - included in OpenClaw. Adds video generation provider support.
 
 - **[searxng](/plugins/reference/searxng)** (`@openclaw/searxng-plugin`) - included in OpenClaw. Adds web search provider support.
@@ -197,8 +161,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[sms](/plugins/reference/sms)** (`@openclaw/sms`) - included in OpenClaw. Twilio SMS channel plugin for OpenClaw text messages.
 
-- **[stepfun](/plugins/reference/stepfun)** (`@openclaw/stepfun-provider`) - included in OpenClaw. Adds StepFun, StepFun Plan model provider support to OpenClaw.
-
 - **[synthetic](/plugins/reference/synthetic)** (`@openclaw/synthetic-provider`) - included in OpenClaw. Adds Synthetic model provider support to OpenClaw.
 
 - **[tavily](/plugins/reference/tavily)** (`@openclaw/tavily-plugin`) - included in OpenClaw. Adds agent-callable tools. Adds web search provider support.
@@ -237,7 +199,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Official external packages
 
-35 plugins
+54 plugins
 
 - **[acpx](/plugins/reference/acpx)** (`@openclaw/acpx`) - npm; ClawHub. OpenClaw ACP runtime backend with plugin-owned session and transport management.
 
@@ -247,12 +209,24 @@ Each entry lists the package, distribution route, and description.
 
 - **[anthropic-vertex](/plugins/reference/anthropic-vertex)** (`@openclaw/anthropic-vertex-provider`) - npm; ClawHub. OpenClaw Anthropic Vertex provider plugin for Claude models on Google Vertex AI.
 
+- **[arcee](/plugins/reference/arcee)** (`@openclaw/arcee-provider`) - npm; ClawHub: `clawhub:@openclaw/arcee-provider`. Adds Arcee model provider support to OpenClaw.
+
 - **[brave](/plugins/reference/brave)** (`@openclaw/brave-plugin`) - npm; ClawHub. OpenClaw Brave Search provider plugin for web search.
 
+- **[cerebras](/plugins/reference/cerebras)** (`@openclaw/cerebras-provider`) - npm; ClawHub: `clawhub:@openclaw/cerebras-provider`. Adds Cerebras model provider support to OpenClaw.
+
+- **[chutes](/plugins/reference/chutes)** (`@openclaw/chutes-provider`) - npm; ClawHub: `clawhub:@openclaw/chutes-provider`. Adds Chutes model provider support to OpenClaw.
+
+- **[cloudflare-ai-gateway](/plugins/reference/cloudflare-ai-gateway)** (`@openclaw/cloudflare-ai-gateway-provider`) - npm; ClawHub: `clawhub:@openclaw/cloudflare-ai-gateway-provider`. Adds Cloudflare AI Gateway model provider support to OpenClaw.
+
 - **[codex](/plugins/reference/codex)** (`@openclaw/codex`) - npm; ClawHub. OpenClaw Codex app-server harness and model provider plugin with a Codex-managed GPT catalog.
 
 - **[copilot](/plugins/reference/copilot)** (`@openclaw/copilot`) - npm; ClawHub: `clawhub:@openclaw/copilot`. Registers the GitHub Copilot agent runtime.
 
+- **[deepinfra](/plugins/reference/deepinfra)** (`@openclaw/deepinfra-provider`) - npm; ClawHub: `clawhub:@openclaw/deepinfra-provider`. Adds DeepInfra model provider support to OpenClaw.
+
+- **[deepseek](/plugins/reference/deepseek)** (`@openclaw/deepseek-provider`) - npm; ClawHub: `clawhub:@openclaw/deepseek-provider`. Adds DeepSeek model provider support to OpenClaw.
+
 - **[diagnostics-otel](/plugins/reference/diagnostics-otel)** (`@openclaw/diagnostics-otel`) - npm; ClawHub: `clawhub:@openclaw/diagnostics-otel`. OpenClaw diagnostics OpenTelemetry exporter for metrics and traces.
 
 - **[diagnostics-prometheus](/plugins/reference/diagnostics-prometheus)** (`@openclaw/diagnostics-prometheus`) - npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus`. OpenClaw diagnostics Prometheus exporter for runtime metrics.
@@ -263,12 +237,28 @@ Each entry lists the package, distribution route, and description.
 
 - **[discord](/plugins/reference/discord)** (`@openclaw/discord`) - npm; ClawHub. OpenClaw Discord channel plugin for channels, DMs, commands, and app events.
 
+- **[exa](/plugins/reference/exa)** (`@openclaw/exa-plugin`) - npm; ClawHub: `clawhub:@openclaw/exa-plugin`. Adds web search provider support.
+
 - **[feishu](/plugins/reference/feishu)** (`@openclaw/feishu`) - npm; ClawHub. OpenClaw Feishu/Lark channel plugin for chats and workplace tools (community maintained by @m1heng).
 
+- **[firecrawl](/plugins/reference/firecrawl)** (`@openclaw/firecrawl-plugin`) - npm; ClawHub: `clawhub:@openclaw/firecrawl-plugin`. Adds agent-callable tools. Adds web fetch provider support. Adds web search provider support.
+
+- **[gmi](/plugins/reference/gmi)** (`@openclaw/gmi-provider`) - npm; ClawHub: `clawhub:@openclaw/gmi-provider`. OpenClaw GMI Cloud provider plugin.
+
 - **[google-meet](/plugins/reference/google-meet)** (`@openclaw/google-meet`) - npm; ClawHub. OpenClaw Google Meet participant plugin for joining calls through Chrome or Twilio transports.
 
 - **[googlechat](/plugins/reference/googlechat)** (`@openclaw/googlechat`) - npm; ClawHub. OpenClaw Google Chat channel plugin for spaces and direct messages.
 
+- **[gradium](/plugins/reference/gradium)** (`@openclaw/gradium-speech`) - npm; ClawHub: `clawhub:@openclaw/gradium-speech`. Adds text-to-speech provider support.
+
+- **[groq](/plugins/reference/groq)** (`@openclaw/groq-provider`) - npm; ClawHub: `clawhub:@openclaw/groq-provider`. Adds Groq model provider support to OpenClaw.
+
+- **[inworld](/plugins/reference/inworld)** (`@openclaw/inworld-speech`) - npm; ClawHub: `clawhub:@openclaw/inworld-speech`. Inworld streaming text-to-speech (MP3, OGG_OPUS, PCM telephony).
+
+- **[kilocode](/plugins/reference/kilocode)** (`@openclaw/kilocode-provider`) - npm; ClawHub: `clawhub:@openclaw/kilocode-provider`. Adds Kilocode model provider support to OpenClaw.
+
+- **[kimi](/plugins/reference/kimi)** (`@openclaw/kimi-provider`) - npm; ClawHub: `clawhub:@openclaw/kimi-provider`. Adds Kimi, Kimi Coding model provider support to OpenClaw.
+
 - **[line](/plugins/reference/line)** (`@openclaw/line`) - npm; ClawHub. OpenClaw LINE channel plugin for LINE Bot API chats.
 
 - **[llama-cpp](/plugins/reference/llama-cpp)** (`@openclaw/llama-cpp-provider`) - npm; ClawHub. Local GGUF embeddings through node-llama-cpp.
@@ -287,12 +277,22 @@ Each entry lists the package, distribution route, and description.
 
 - **[openshell](/plugins/reference/openshell)** (`@openclaw/openshell-sandbox`) - npm; ClawHub. OpenClaw sandbox backend for the NVIDIA OpenShell CLI with mirrored local workspaces and SSH command execution.
 
+- **[parallel](/tools/parallel-search)** (`@openclaw/parallel-plugin`) - npm; ClawHub: `clawhub:@openclaw/parallel-plugin`. Adds web search provider support.
+
+- **[perplexity](/plugins/reference/perplexity)** (`@openclaw/perplexity-plugin`) - npm; ClawHub: `clawhub:@openclaw/perplexity-plugin`. Adds web search provider support.
+
 - **[pixverse](/plugins/reference/pixverse)** (`@openclaw/pixverse-provider`) - npm; ClawHub: `clawhub:@openclaw/pixverse-provider`. OpenClaw PixVerse video generation provider plugin.
 
+- **[qianfan](/plugins/reference/qianfan)** (`@openclaw/qianfan-provider`) - npm; ClawHub: `clawhub:@openclaw/qianfan-provider`. Adds Qianfan model provider support to OpenClaw.
+
 - **[qqbot](/plugins/reference/qqbot)** (`@openclaw/qqbot`) - npm; ClawHub. OpenClaw QQ Bot channel plugin for group and direct-message workflows.
 
+- **[qwen](/plugins/reference/qwen)** (`@openclaw/qwen-provider`) - npm; ClawHub: `clawhub:@openclaw/qwen-provider`. Adds Qwen, Qwen Cloud, Model Studio, DashScope, Qwen Oauth, Qwen Portal, Qwen CLI model provider support to OpenClaw.
+
 - **[slack](/plugins/reference/slack)** (`@openclaw/slack`) - npm; ClawHub. OpenClaw Slack channel plugin for channels, DMs, commands, and app events.
 
+- **[stepfun](/plugins/reference/stepfun)** (`@openclaw/stepfun-provider`) - npm; ClawHub: `clawhub:@openclaw/stepfun-provider`. Adds StepFun, StepFun Plan model provider support to OpenClaw.
+
 - **[synology-chat](/plugins/reference/synology-chat)** (`@openclaw/synology-chat`) - npm; ClawHub. Synology Chat channel plugin for OpenClaw channels and direct messages.
 
 - **[tlon](/plugins/reference/tlon)** (`@openclaw/tlon`) - npm; ClawHub. OpenClaw Tlon/Urbit channel plugin for chat workflows.

docs/plugins/reference/arcee.md

@@ -12,7 +12,7 @@ Adds Arcee model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/arcee-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/arcee-provider`
 
 ## Surface
 

docs/plugins/reference/cerebras.md

@@ -12,7 +12,7 @@ Adds Cerebras model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/cerebras-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/cerebras-provider`
 
 ## Surface
 

docs/plugins/reference/chutes.md

@@ -12,7 +12,7 @@ Adds Chutes model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/chutes-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/chutes-provider`
 
 ## Surface
 

docs/plugins/reference/cloudflare-ai-gateway.md

@@ -12,7 +12,7 @@ Adds Cloudflare AI Gateway model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/cloudflare-ai-gateway-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/cloudflare-ai-gateway-provider`
 
 ## Surface
 

docs/plugins/reference/cohere.md

@@ -1,5 +1,5 @@
 ---
-summary: "Adds Cohere model provider support to OpenClaw."
+summary: "OpenClaw Cohere provider plugin."
 read_when:
   - You are installing, configuring, or auditing the cohere plugin
 title: "Cohere plugin"
@@ -7,12 +7,12 @@ title: "Cohere plugin"
 
 # Cohere plugin
 
-Adds Cohere model provider support to OpenClaw.
+OpenClaw Cohere provider plugin.
 
 ## Distribution
 
 - Package: `@openclaw/cohere-provider`
-- Install route: included in OpenClaw
+- Install route: included in OpenClaw; npm; ClawHub: `clawhub:@openclaw/cohere-provider`
 
 ## Surface
 

docs/plugins/reference/deepinfra.md

@@ -12,7 +12,7 @@ Adds DeepInfra model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/deepinfra-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/deepinfra-provider`
 
 ## Surface
 

docs/plugins/reference/deepseek.md

@@ -12,7 +12,7 @@ Adds DeepSeek model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/deepseek-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/deepseek-provider`
 
 ## Surface
 

docs/plugins/reference/exa.md

@@ -12,7 +12,7 @@ Adds web search provider support.
 ## Distribution
 
 - Package: `@openclaw/exa-plugin`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/exa-plugin`
 
 ## Surface
 

docs/plugins/reference/firecrawl.md

@@ -12,7 +12,7 @@ Adds agent-callable tools. Adds web fetch provider support. Adds web search prov
 ## Distribution
 
 - Package: `@openclaw/firecrawl-plugin`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/firecrawl-plugin`
 
 ## Surface
 

docs/plugins/reference/gmi.md

@@ -1,5 +1,5 @@
 ---
-summary: "Adds Gmi, Gmi Cloud, Gmicloud model provider support to OpenClaw."
+summary: "OpenClaw GMI Cloud provider plugin."
 read_when:
   - You are installing, configuring, or auditing the gmi plugin
 title: "Gmi plugin"
@@ -7,12 +7,12 @@ title: "Gmi plugin"
 
 # Gmi plugin
 
-Adds Gmi, Gmi Cloud, Gmicloud model provider support to OpenClaw.
+OpenClaw GMI Cloud provider plugin.
 
 ## Distribution
 
 - Package: `@openclaw/gmi-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/gmi-provider`
 
 ## Surface
 

docs/plugins/reference/gradium.md

@@ -12,7 +12,7 @@ Adds text-to-speech provider support.
 ## Distribution
 
 - Package: `@openclaw/gradium-speech`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/gradium-speech`
 
 ## Surface
 

docs/plugins/reference/groq.md

@@ -12,7 +12,7 @@ Adds Groq model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/groq-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/groq-provider`
 
 ## Surface
 

docs/plugins/reference/inworld.md

@@ -12,7 +12,7 @@ Inworld streaming text-to-speech (MP3, OGG_OPUS, PCM telephony).
 ## Distribution
 
 - Package: `@openclaw/inworld-speech`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/inworld-speech`
 
 ## Surface
 

docs/plugins/reference/kilocode.md

@@ -12,7 +12,7 @@ Adds Kilocode model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/kilocode-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/kilocode-provider`
 
 ## Surface
 

docs/plugins/reference/kimi.md

@@ -12,7 +12,7 @@ Adds Kimi, Kimi Coding model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/kimi-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/kimi-provider`
 
 ## Surface
 

docs/plugins/reference/perplexity.md

@@ -12,7 +12,7 @@ Adds web search provider support.
 ## Distribution
 
 - Package: `@openclaw/perplexity-plugin`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/perplexity-plugin`
 
 ## Surface
 

docs/plugins/reference/qa-lab.md

@@ -16,4 +16,4 @@ OpenClaw QA lab plugin with private debugger UI and scenario runner.
 
 ## Surface
 
-plugin
+contracts: webSearchProviders

docs/plugins/reference/qianfan.md

@@ -12,7 +12,7 @@ Adds Qianfan model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/qianfan-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/qianfan-provider`
 
 ## Surface
 

docs/plugins/reference/qwen.md

@@ -12,7 +12,7 @@ Adds Qwen, Qwen Cloud, Model Studio, DashScope, Qwen Oauth, Qwen Portal, Qwen CL
 ## Distribution
 
 - Package: `@openclaw/qwen-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/qwen-provider`
 
 ## Surface
 

docs/plugins/reference/stepfun.md

@@ -12,7 +12,7 @@ Adds StepFun, StepFun Plan model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/stepfun-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/stepfun-provider`
 
 ## Surface
 

docs/plugins/sdk-subpaths.md

@@ -248,6 +248,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
     | `plugin-sdk/reply-chunking` | Narrow text/markdown chunking helpers |
     | `plugin-sdk/session-store-runtime` | Session workflow helpers (`getSessionEntry`, `listSessionEntries`, `patchSessionEntry`, `upsertSessionEntry`), legacy session store path/session-key helpers, updated-at reads, and deprecated whole-store mutation helpers |
+    | `plugin-sdk/sqlite-runtime` | Focused SQLite agent-schema, path, and transaction helpers for first-party runtime |
     | `plugin-sdk/cron-store-runtime` | Cron store path/load/save helpers |
     | `plugin-sdk/state-paths` | State/OAuth dir path helpers |
     | `plugin-sdk/plugin-state-runtime` | Plugin sidecar SQLite keyed-state types plus centralized connection pragma and WAL maintenance setup for plugin-owned databases |
@@ -306,6 +307,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/response-limit-runtime` | Bounded response-body reader without the broad media runtime surface |
     | `plugin-sdk/session-binding-runtime` | Current conversation binding state without configured binding routing or pairing stores |
     | `plugin-sdk/session-store-runtime` | Session-store helpers without broad config writes/maintenance imports |
+    | `plugin-sdk/sqlite-runtime` | Focused SQLite agent-schema, path, and transaction helpers without database lifecycle controls |
     | `plugin-sdk/context-visibility-runtime` | Context visibility resolution and supplemental context filtering without broad config/security imports |
     | `plugin-sdk/string-coerce-runtime` | Narrow primitive record/string coercion and normalization helpers without markdown/logging imports |
     | `plugin-sdk/host-runtime` | Hostname and SCP host normalization helpers |

docs/providers/arcee.md

@@ -17,6 +17,15 @@ Arcee AI models can be accessed directly via the Arcee platform or through [Open
 | API      | OpenAI-compatible                                                                     |
 | Base URL | `https://api.arcee.ai/api/v1` (direct) or `https://openrouter.ai/api/v1` (OpenRouter) |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/arcee-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Tabs>
@@ -96,7 +105,7 @@ Arcee AI models can be accessed directly via the Arcee platform or through [Open
 
 ## Built-in catalog
 
-OpenClaw currently ships this bundled Arcee catalog:
+OpenClaw currently ships this Arcee static catalog:
 
 | Model ref                      | Name                   | Input | Context | Cost (in/out per 1M) | Notes                                     |
 | ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |

docs/providers/bedrock.md

@@ -371,15 +371,17 @@ openclaw models list
   <Accordion title="Embeddings for memory search">
     Bedrock can also serve as the embedding provider for
     [memory search](/concepts/memory-search). This is configured separately from the
-    inference provider -- set `agents.defaults.memorySearch.provider` to `"bedrock"`:
+    inference provider -- set `agents.defaults.memory.search.provider` to `"bedrock"`:
 
     ```json5
     {
       agents: {
         defaults: {
-          memorySearch: {
-            provider: "bedrock",
-            model: "amazon.titan-embed-text-v2:0", // default
+          memory: {
+            search: {
+              provider: "bedrock",
+              model: "amazon.titan-embed-text-v2:0", // default
+            },
           },
         },
       },
@@ -388,7 +390,7 @@ openclaw models list
 
     Bedrock embeddings use the same AWS SDK credential chain as inference (instance
     roles, SSO, access keys, shared config, and web identity). No API key is
-    needed. Set `memorySearch.provider: "bedrock"` explicitly to use Bedrock
+    needed. Set `memory.search.provider: "bedrock"` explicitly to use Bedrock
     embeddings.
 
     Supported embedding models include Amazon Titan Embed (v1, v2), Amazon Nova

docs/providers/cerebras.md

@@ -6,12 +6,12 @@ read_when:
   - You need the Cerebras API key env var or CLI auth choice
 ---
 
-[Cerebras](https://www.cerebras.ai) provides high-speed OpenAI-compatible inference on custom inference hardware. OpenClaw includes a bundled Cerebras provider plugin with a static four-model catalog.
+[Cerebras](https://www.cerebras.ai) provides high-speed OpenAI-compatible inference on custom inference hardware. The Cerebras provider plugin includes a static four-model catalog.
 
 | Property        | Value                                    |
 | --------------- | ---------------------------------------- |
 | Provider id     | `cerebras`                               |
-| Plugin          | bundled, `enabledByDefault: true`        |
+| Plugin          | official external package                |
 | Auth env var    | `CEREBRAS_API_KEY`                       |
 | Onboarding flag | `--auth-choice cerebras-api-key`         |
 | Direct CLI flag | `--cerebras-api-key <key>`               |
@@ -19,6 +19,15 @@ read_when:
 | Base URL        | `https://api.cerebras.ai/v1`             |
 | Default model   | `cerebras/zai-glm-4.7`                   |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/cerebras-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -50,7 +59,7 @@ export CEREBRAS_API_KEY=csk-...
     openclaw models list --provider cerebras
     ```
 
-    The list should include all four bundled models. If `CEREBRAS_API_KEY` is unresolved, `openclaw models status --json` reports the missing credential under `auth.unusableProfiles`.
+    The list should include all four static models. If `CEREBRAS_API_KEY` is unresolved, `openclaw models status --json` reports the missing credential under `auth.unusableProfiles`.
 
   </Step>
 </Steps>
@@ -81,7 +90,7 @@ OpenClaw ships a static Cerebras catalog that mirrors the public OpenAI-compatib
 
 ## Manual config
 
-The bundled plugin usually means you only need the API key. Use explicit `models.providers.cerebras` config when you want to override model metadata or run in `mode: "merge"` against the static catalog:
+The plugin usually means you only need the API key. Use explicit `models.providers.cerebras` config when you want to override model metadata or run in `mode: "merge"` against the static catalog:
 
 ```json5
 {

docs/providers/chutes.md

@@ -9,7 +9,7 @@ read_when:
 
 [Chutes](https://chutes.ai) exposes open-source model catalogs through an
 OpenAI-compatible API. OpenClaw supports both browser OAuth and direct API-key
-auth for the bundled `chutes` provider.
+auth for the `chutes` provider.
 
 | Property | Value                        |
 | -------- | ---------------------------- |
@@ -18,6 +18,15 @@ auth for the bundled `chutes` provider.
 | Base URL | `https://llm.chutes.ai/v1`   |
 | Auth     | OAuth or API key (see below) |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/chutes-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Tabs>
@@ -33,7 +42,7 @@ auth for the bundled `chutes` provider.
       </Step>
       <Step title="Verify the default model">
         After onboarding, the default model is set to
-        `chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
+        `chutes/zai-org/GLM-4.7-TEE` and the Chutes static catalog is
         registered.
       </Step>
     </Steps>
@@ -51,7 +60,7 @@ auth for the bundled `chutes` provider.
       </Step>
       <Step title="Verify the default model">
         After onboarding, the default model is set to
-        `chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
+        `chutes/zai-org/GLM-4.7-TEE` and the Chutes static catalog is
         registered.
       </Step>
     </Steps>
@@ -59,7 +68,7 @@ auth for the bundled `chutes` provider.
 </Tabs>
 
 <Note>
-Both auth paths register the bundled Chutes catalog and set the default model to
+Both auth paths register the Chutes static catalog and set the default model to
 `chutes/zai-org/GLM-4.7-TEE`. Runtime environment variables: `CHUTES_API_KEY`,
 `CHUTES_OAUTH_TOKEN`.
 </Note>
@@ -68,11 +77,11 @@ Both auth paths register the bundled Chutes catalog and set the default model to
 
 When Chutes auth is available, OpenClaw queries the Chutes catalog with that
 credential and uses the discovered models. If discovery fails, OpenClaw falls
-back to a bundled static catalog so onboarding and startup still work.
+back to a static catalog so onboarding and startup still work.
 
 ## Default aliases
 
-OpenClaw registers three convenience aliases for the bundled Chutes catalog:
+OpenClaw registers three convenience aliases for the Chutes static catalog:
 
 | Alias           | Target model                                          |
 | --------------- | ----------------------------------------------------- |
@@ -82,7 +91,7 @@ OpenClaw registers three convenience aliases for the bundled Chutes catalog:
 
 ## Built-in starter catalog
 
-The bundled fallback catalog includes current Chutes refs:
+The static fallback catalog includes current Chutes refs:
 
 | Model ref                                             |
 | ----------------------------------------------------- |
@@ -130,7 +139,7 @@ The bundled fallback catalog includes current Chutes refs:
   <Accordion title="Notes">
     - API-key and OAuth discovery both use the same `chutes` provider id.
     - Chutes models are registered as `chutes/<model-id>`.
-    - If discovery fails at startup, the bundled static catalog is used automatically.
+    - If discovery fails at startup, the static catalog is used automatically.
 
   </Accordion>
 </AccordionGroup>

docs/providers/cloudflare-ai-gateway.md

@@ -24,6 +24,15 @@ assistant prefill turns before sending the payload through Cloudflare AI Gateway
 Anthropic rejects response prefilling with extended thinking, while ordinary
 non-thinking prefill remains available.
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/cloudflare-ai-gateway-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>

docs/providers/cohere.md

@@ -6,23 +6,30 @@ read_when:
   - You need the Cohere API key env var or CLI auth choice
 ---
 
-[Cohere](https://cohere.com) provides OpenAI-compatible inference through its Compatibility API. OpenClaw includes a bundled Cohere provider plugin with the Command A model catalog.
+[Cohere](https://cohere.com) provides OpenAI-compatible inference through its Compatibility API. OpenClaw ships the Cohere provider during its externalization transition and also publishes it as an official external plugin with the Command A model catalog.
 
-| Property        | Value                                    |
-| --------------- | ---------------------------------------- |
-| Provider id     | `cohere`                                 |
-| Plugin          | bundled, `enabledByDefault: true`        |
-| Auth env var    | `COHERE_API_KEY`                         |
-| Onboarding flag | `--auth-choice cohere-api-key`           |
-| Direct CLI flag | `--cohere-api-key <key>`                 |
-| API             | OpenAI-compatible (`openai-completions`) |
-| Base URL        | `https://api.cohere.ai/compatibility/v1` |
-| Default model   | `cohere/command-a-03-2025`               |
+| Property        | Value                                                |
+| --------------- | ---------------------------------------------------- |
+| Provider id     | `cohere`                                             |
+| Plugin          | bundled during transition; official external package |
+| Auth env var    | `COHERE_API_KEY`                                     |
+| Onboarding flag | `--auth-choice cohere-api-key`                       |
+| Direct CLI flag | `--cohere-api-key <key>`                             |
+| API             | OpenAI-compatible (`openai-completions`)             |
+| Base URL        | `https://api.cohere.ai/compatibility/v1`             |
+| Default model   | `cohere/command-a-03-2025`                           |
 
 ## Get started
 
-1. Create a Cohere API key.
-2. Run onboarding:
+1. Cohere is included in current OpenClaw packages. If it is unavailable, install the external package and restart the Gateway:
+
+```bash
+openclaw plugins install @openclaw/cohere-provider
+openclaw gateway restart
+```
+
+2. Create a Cohere API key.
+3. Run onboarding:
 
 ```bash
 openclaw onboard --non-interactive \
@@ -30,7 +37,7 @@ openclaw onboard --non-interactive \
   --cohere-api-key "$COHERE_API_KEY"
 ```
 
-3. Confirm the catalog is available:
+4. Confirm the catalog is available:
 
 ```bash
 openclaw models list --provider cohere
@@ -40,7 +47,7 @@ The default model is set only when no primary model is already configured.
 
 ## Environment-only setup
 
-Make `COHERE_API_KEY` available to the Gateway process, then select the bundled model:
+Make `COHERE_API_KEY` available to the Gateway process, then select the Cohere model:
 
 ```json5
 {

docs/providers/deepinfra.md

@@ -9,6 +9,15 @@ title: "DeepInfra"
 DeepInfra provides a **unified API** that routes requests to the most popular open source and frontier models behind a single
 endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/deepinfra-provider
+openclaw gateway restart
+```
+
 ## Getting an API key
 
 1. Go to [https://deepinfra.com/](https://deepinfra.com/)
@@ -42,7 +51,7 @@ export DEEPINFRA_API_KEY="<your-deepinfra-api-key>" # pragma: allowlist secret
 
 ## Supported OpenClaw surfaces
 
-The bundled plugin registers all DeepInfra surfaces that match current
+The plugin registers all DeepInfra surfaces that match current
 OpenClaw provider contracts. Chat, image generation, and video generation
 refresh their model catalogues live from `/v1/openai/models?sort_by=openclaw&filter=with_meta`
 when `DEEPINFRA_API_KEY` is configured; the other surfaces use the curated
@@ -56,7 +65,7 @@ static defaults below.
 | Speech-to-text           | `openai/whisper-large-v3-turbo`                                                                       | inbound audio transcription                              |
 | Text-to-speech           | `hexgrad/Kokoro-82M`                                                                                  | `messages.tts.provider: "deepinfra"`                     |
 | Video generation         | first `video-gen`-tagged entry from live catalog (static fallback `Pixverse/Pixverse-T2V`)            | `video_generate`, `agents.defaults.videoGenerationModel` |
-| Memory embeddings        | `BAAI/bge-m3`                                                                                         | `agents.defaults.memorySearch.provider: "deepinfra"`     |
+| Memory embeddings        | `BAAI/bge-m3`                                                                                         | `agents.defaults.memory.search.provider: "deepinfra"`    |
 
 DeepInfra also exposes reranking, classification, object-detection, and other
 native model types. OpenClaw does not currently have first-class provider

docs/providers/deepseek.md

@@ -15,6 +15,15 @@ read_when:
 | API      | OpenAI-compatible          |
 | Base URL | `https://api.deepseek.com` |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/deepseek-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -34,7 +43,7 @@ read_when:
     openclaw models list --provider deepseek
     ```
 
-    To inspect the bundled static catalog without requiring a running Gateway,
+    To inspect the plugin's static catalog without requiring a running Gateway,
     use:
 
     ```bash

docs/providers/github-copilot.md

@@ -216,7 +216,7 @@ have logged in, OpenClaw can use it for embeddings without a separate API key.
 
 ### Config
 
-Set `memorySearch.provider` explicitly to use GitHub Copilot embeddings. If a
+Set `memory.search.provider` explicitly to use GitHub Copilot embeddings. If a
 GitHub token is available, OpenClaw discovers available embedding models from
 the Copilot API and picks the best one automatically.
 
@@ -224,10 +224,12 @@ the Copilot API and picks the best one automatically.
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "github-copilot",
-        // Optional: override the auto-discovered model
-        model: "text-embedding-3-small",
+      memory: {
+        search: {
+          provider: "github-copilot",
+          // Optional: override the auto-discovered model
+          model: "text-embedding-3-small",
+        },
       },
     },
   },

docs/providers/gmi.md

@@ -7,9 +7,9 @@ title: "GMI Cloud"
 ---
 
 GMI Cloud is a hosted inference platform for frontier and open-weight models
-behind an OpenAI-compatible API. In OpenClaw it is a bundled model provider,
-which means you can select it with the provider id `gmi`, store credentials
-through normal model auth, and use model refs like
+behind an OpenAI-compatible API. In OpenClaw it is an official external provider
+plugin, which means you install it once, select it with the provider id `gmi`,
+store credentials through normal model auth, and use model refs like
 `gmi/google/gemini-3.1-flash-lite`.
 
 Use GMI when you want one API key for several hosted model families, including
@@ -24,7 +24,14 @@ model availability, billing, rate limits, and any provider-side routing policy.
 
 ## Setup
 
-Create an API key in GMI Cloud, then run:
+Install the plugin, restart the gateway, then create an API key in GMI Cloud:
+
+```bash
+openclaw plugins install @openclaw/gmi-provider
+openclaw gateway restart
+```
+
+Then run:
 
 ```bash
 openclaw onboard --auth-choice gmi-api-key
@@ -60,7 +67,7 @@ GPU control matters more than hosted convenience.
 
 ## Models
 
-The bundled catalog seeds commonly available GMI Cloud route ids, including:
+The plugin catalog seeds commonly available GMI Cloud route ids, including:
 
 - `gmi/zai-org/GLM-5.1-FP8`
 - `gmi/deepseek-ai/DeepSeek-V3.2`

docs/providers/gradium.md

@@ -6,7 +6,7 @@ read_when:
 title: "Gradium"
 ---
 
-[Gradium](https://gradium.ai) is a bundled text-to-speech provider for OpenClaw. The plugin can render normal audio replies (WAV), voice-note-compatible Opus output, and 8 kHz u-law audio for telephony surfaces.
+[Gradium](https://gradium.ai) is a text-to-speech provider for OpenClaw. The plugin can render normal audio replies (WAV), voice-note-compatible Opus output, and 8 kHz u-law audio for telephony surfaces.
 
 | Property      | Value                                |
 | ------------- | ------------------------------------ |
@@ -15,6 +15,15 @@ title: "Gradium"
 | Base URL      | `https://api.gradium.ai` (default)   |
 | Default voice | `Emma` (`YTpq7expH9539ERJ`)          |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/gradium-speech
+openclaw gateway restart
+```
+
 ## Setup
 
 Create a Gradium API key, then expose it to OpenClaw with either an env var or the config key.

docs/providers/groq.md

@@ -7,19 +7,27 @@ read_when:
   - You are configuring Whisper audio transcription on Groq
 ---
 
-[Groq](https://groq.com) provides ultra-fast inference on open-weight models (Llama, Gemma, Kimi, Qwen, GPT OSS, and more) using custom LPU hardware. OpenClaw includes a bundled Groq plugin that registers both an OpenAI-compatible chat provider and an audio media-understanding provider.
+[Groq](https://groq.com) provides ultra-fast inference on open-weight models (Llama, Gemma, Kimi, Qwen, GPT OSS, and more) using custom LPU hardware. The Groq plugin registers both an OpenAI-compatible chat provider and an audio media-understanding provider.
 
 | Property               | Value                                    |
 | ---------------------- | ---------------------------------------- |
 | Provider id            | `groq`                                   |
-| Plugin                 | bundled, `enabledByDefault: true`        |
+| Plugin                 | official external package                |
 | Auth env var           | `GROQ_API_KEY`                           |
-| Onboarding flag        | `--auth-choice groq-api-key`             |
 | API                    | OpenAI-compatible (`openai-completions`) |
 | Base URL               | `https://api.groq.com/openai/v1`         |
 | Audio transcription    | `whisper-large-v3-turbo` (default)       |
 | Suggested chat default | `groq/llama-3.3-70b-versatile`           |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/groq-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -27,18 +35,9 @@ read_when:
     Create an API key at [console.groq.com/keys](https://console.groq.com/keys).
   </Step>
   <Step title="Set the API key">
-    <CodeGroup>
-
-```bash Onboarding
-openclaw onboard --auth-choice groq-api-key
-```
-
-```bash Env only
+    ```bash
 export GROQ_API_KEY=gsk_...
 ```
-
-    </CodeGroup>
-
   </Step>
   <Step title="Set a default model">
     ```json5
@@ -73,7 +72,7 @@ export GROQ_API_KEY=gsk_...
 
 ## Built-in catalog
 
-OpenClaw ships a manifest-backed Groq catalog with both reasoning and non-reasoning entries. Run `openclaw models list --provider groq` to see the bundled rows for your installed version, or check [console.groq.com/docs/models](https://console.groq.com/docs/models) for Groq's authoritative list.
+OpenClaw ships a manifest-backed Groq catalog with both reasoning and non-reasoning entries. Run `openclaw models list --provider groq` to see the static rows for your installed version, or check [console.groq.com/docs/models](https://console.groq.com/docs/models) for Groq's authoritative list.
 
 | Model ref                                        | Name                    | Reasoning | Input        | Context |
 | ------------------------------------------------ | ----------------------- | --------- | ------------ | ------- |
@@ -103,7 +102,7 @@ See [Thinking modes](/tools/thinking) for the shared `/think` levels and how Ope
 
 ## Audio transcription
 
-Groq's bundled plugin also registers an **audio media-understanding provider** so voice messages can be transcribed through the shared `tools.media.audio` surface.
+Groq's plugin also registers an **audio media-understanding provider** so voice messages can be transcribed through the shared `tools.media.audio` surface.
 
 | Property           | Value                                     |
 | ------------------ | ----------------------------------------- |
@@ -138,7 +137,7 @@ To make Groq the default audio backend:
   </Accordion>
 
   <Accordion title="Custom Groq model ids">
-    OpenClaw accepts any Groq model id at runtime. Use the exact id shown by Groq and prefix it with `groq/`. The bundled catalog covers the common cases; uncatalogued ids fall through to the default OpenAI-compatible template.
+    OpenClaw accepts any Groq model id at runtime. Use the exact id shown by Groq and prefix it with `groq/`. The static catalog covers the common cases; uncatalogued ids fall through to the default OpenAI-compatible template.
 
     ```json5
     {

docs/providers/inworld.md

@@ -17,7 +17,7 @@ the standard reply-audio pipeline.
 | Property      | Value                                                           |
 | ------------- | --------------------------------------------------------------- |
 | Provider id   | `inworld`                                                       |
-| Plugin        | bundled, `enabledByDefault: true`                               |
+| Plugin        | official external package                                       |
 | Contract      | `speechProviders` (TTS only)                                    |
 | Auth env var  | `INWORLD_API_KEY` (HTTP Basic, Base64 dashboard credential)     |
 | Base URL      | `https://api.inworld.ai`                                        |
@@ -27,6 +27,15 @@ the standard reply-audio pipeline.
 | Website       | [inworld.ai](https://inworld.ai)                                |
 | Docs          | [docs.inworld.ai/tts/tts](https://docs.inworld.ai/tts/tts)      |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/inworld-speech
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -112,7 +121,7 @@ the standard reply-audio pipeline.
     Full config reference including `messages.tts` settings.
   </Card>
   <Card title="Providers" href="/providers" icon="grid">
-    All bundled OpenClaw providers.
+    All supported OpenClaw providers.
   </Card>
   <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
     Common issues and debugging steps.

docs/providers/kilocode.md

@@ -16,6 +16,15 @@ endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switc
 | API      | OpenAI-compatible                  |
 | Base URL | `https://api.kilo.ai/api/gateway/` |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/kilocode-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -70,7 +79,7 @@ Any model available on the gateway can be used with the `kilocode/` prefix:
 
 <Tip>
 At startup, OpenClaw queries `GET https://api.kilo.ai/api/gateway/models` and merges
-discovered models ahead of the static fallback catalog. The bundled fallback always
+discovered models ahead of the static fallback catalog. The static fallback always
 includes `kilocode/kilo/auto` (`Kilo Auto`) with `input: ["text", "image"]`,
 `reasoning: true`, `contextWindow: 1000000`, and `maxTokens: 128000`.
 </Tip>
@@ -113,7 +122,7 @@ includes `kilocode/kilo/auto` (`Kilo Auto`) with `input: ["text", "image"]`,
   </Accordion>
 
   <Accordion title="Troubleshooting">
-    - If model discovery fails at startup, OpenClaw falls back to the bundled static catalog containing `kilocode/kilo/auto`.
+    - If model discovery fails at startup, OpenClaw falls back to the static catalog containing `kilocode/kilo/auto`.
     - Confirm your API key is valid and that your Kilo account has the desired models enabled.
     - When the Gateway runs as a daemon, ensure `KILOCODE_API_KEY` is available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
 

docs/providers/mistral.md

@@ -208,7 +208,13 @@ matching `sampleRate` only if your upstream stream is already raw PCM.
 
     ```json5
     {
-      memorySearch: { provider: "mistral" },
+      agents: {
+        defaults: {
+          memory: {
+            search: { provider: "mistral" },
+          },
+        },
+      },
     }
     ```
 

docs/providers/moonshot.md

@@ -200,6 +200,12 @@ Choose your provider and follow the setup steps.
   </Tab>
 
   <Tab title="Kimi Coding">
+    Install the official plugin, then restart Gateway:
+
+    ```bash
+    openclaw plugins install @openclaw/kimi-provider
+    openclaw gateway restart
+    ```
     **Best for:** code-focused tasks via the Kimi Coding endpoint.
 
     <Note>

docs/providers/ollama.md

@@ -31,7 +31,7 @@ Ollama provider config uses `baseUrl` as the canonical key. OpenClaw also accept
     Remote public hosts and Ollama Cloud (`https://ollama.com`) require a real credential through `OLLAMA_API_KEY`, an auth profile, or the provider's `apiKey`. For direct hosted use, prefer provider `ollama-cloud`.
   </Accordion>
   <Accordion title="Custom provider ids">
-    Custom provider ids that set `api: "ollama"` follow the same rules. For example, an `ollama-remote` provider that points at a private LAN Ollama host can use `apiKey: "ollama-local"` and sub-agents will resolve that marker through the Ollama provider hook instead of treating it as a missing credential. Memory search can also set `agents.defaults.memorySearch.provider` to that custom provider id so embeddings use the matching Ollama endpoint.
+    Custom provider ids that set `api: "ollama"` follow the same rules. For example, an `ollama-remote` provider that points at a private LAN Ollama host can use `apiKey: "ollama-local"` and sub-agents will resolve that marker through the Ollama provider hook instead of treating it as a missing credential. Memory search can also set `agents.defaults.memory.search.provider` to that custom provider id so embeddings use the matching Ollama endpoint.
   </Accordion>
   <Accordion title="Auth profiles">
     `auth-profiles.json` stores the credential for a provider id. Put endpoint settings (`baseUrl`, `api`, model ids, headers, timeouts) in `models.providers.<id>`. Older flat auth-profile files such as `{ "ollama-windows": { "apiKey": "ollama-local" } }` are not a runtime format; run `openclaw doctor --fix` to rewrite them to the canonical `ollama-windows:default` API-key profile with a backup. `baseUrl` in that file is compatibility noise and should be moved to provider config.
@@ -40,7 +40,7 @@ Ollama provider config uses `baseUrl` as the canonical key. OpenClaw also accept
     When Ollama is used for memory embeddings, bearer auth is scoped to the host where it was declared:
 
     - A provider-level key is sent only to that provider's Ollama host.
-    - `agents.*.memorySearch.remote.apiKey` is sent only to its remote embedding host.
+    - `agents.*.memory.search.remote.apiKey` is sent only to its remote embedding host.
     - A pure `OLLAMA_API_KEY` env value is treated as the Ollama Cloud convention, not sent to local or self-hosted hosts by default.
 
   </Accordion>
@@ -974,11 +974,13 @@ For the full setup and behavior details, see [Ollama Web Search](/tools/ollama-s
     {
       agents: {
         defaults: {
-          memorySearch: {
-            provider: "ollama",
-            remote: {
-              // Default for Ollama. Raise on larger hosts if reindexing is too slow.
-              nonBatchConcurrency: 1,
+          memory: {
+            search: {
+              provider: "ollama",
+              remote: {
+                // Default for Ollama. Raise on larger hosts if reindexing is too slow.
+                nonBatchConcurrency: 1,
+              },
             },
           },
         },
@@ -992,13 +994,15 @@ For the full setup and behavior details, see [Ollama Web Search](/tools/ollama-s
     {
       agents: {
         defaults: {
-          memorySearch: {
-            provider: "ollama",
-            model: "nomic-embed-text",
-            remote: {
-              baseUrl: "http://gpu-box.local:11434",
-              apiKey: "ollama-local",
-              nonBatchConcurrency: 2,
+          memory: {
+            search: {
+              provider: "ollama",
+              model: "nomic-embed-text",
+              remote: {
+                baseUrl: "http://gpu-box.local:11434",
+                apiKey: "ollama-local",
+                nonBatchConcurrency: 2,
+              },
             },
           },
         },

docs/providers/openai.md

@@ -125,9 +125,11 @@ OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "openai",
-        model: "text-embedding-3-small",
+      memory: {
+        search: {
+          provider: "openai",
+          model: "text-embedding-3-small",
+        },
       },
     },
   },
@@ -135,7 +137,7 @@ OpenClaw can use OpenAI, or an OpenAI-compatible embedding endpoint, for
 ```
 
 For OpenAI-compatible endpoints that require asymmetric embedding labels, set
-`queryInputType` and `documentInputType` under `memorySearch`. OpenClaw forwards
+`queryInputType` and `documentInputType` under `memory.search`. OpenClaw forwards
 those as provider-specific `input_type` request fields: query embeddings use
 `queryInputType`; indexed memory chunks and batch indexing use
 `documentInputType`. See the [Memory configuration reference](/reference/memory-config#provider-specific-config) for the full example.
@@ -506,6 +508,9 @@ openclaw infer image generate \
 Use the same `--output-format` and `--background` flags with
 `openclaw infer image edit` when starting from an input file.
 `--openai-background` remains available as an OpenAI-specific alias.
+Use `--quality low|medium|high|auto` when you need to control OpenAI Images
+quality and cost. Use `--openai-moderation low|auto` to pass OpenAI's
+provider-specific moderation hint from either `image generate` or `image edit`.
 
 For ChatGPT/Codex OAuth installs, keep the same `openai/gpt-image-2` ref. When an
 `openai` OAuth profile is configured, OpenClaw resolves that stored OAuth

docs/providers/perplexity-provider.md

@@ -19,6 +19,15 @@ This page is the Perplexity **provider** setup. For the Perplexity **tool** (how
 | Auth        | `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
 | Config path | `plugins.entries.perplexity.config.webSearch.apiKey`                   |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/perplexity-plugin
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>

docs/providers/qianfan.md

@@ -16,6 +16,15 @@ endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switc
 | API      | OpenAI-compatible                 |
 | Base URL | `https://qianfan.baidubce.com/v2` |
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/qianfan-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 <Steps>
@@ -45,7 +54,7 @@ endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switc
 | `qianfan/ernie-5.0-thinking-preview` | text, image | 119,000 | 64,000     | Yes       | Multimodal    |
 
 <Tip>
-The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
+The default model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
 </Tip>
 
 ## Config example
@@ -98,7 +107,7 @@ The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to overr
   </Accordion>
 
   <Accordion title="Catalog and overrides">
-    The bundled catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
+    The static catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
 
     <Note>
     Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v3.2`).

docs/providers/qwen-oauth.md

@@ -64,11 +64,11 @@ provider instead.
 - You need to test compatibility with the Qwen Portal endpoint specifically.
 
 Choose [Qwen](/providers/qwen) for new setup, broader endpoint choices, Standard
-ModelStudio, Coding Plan, and the full bundled Qwen catalog.
+ModelStudio, Coding Plan, and the full Qwen plugin catalog.
 
 ## Models
 
-The bundled catalog seeds the Qwen Portal default:
+The Qwen plugin catalog seeds the Qwen Portal default:
 
 - `qwen-oauth/qwen3.5-plus`
 

docs/providers/qwen.md

@@ -1,13 +1,13 @@
 ---
-summary: "Use Qwen Cloud via OpenClaw's bundled qwen provider"
+summary: "Use Qwen Cloud through its OpenClaw plugin"
 read_when:
   - You want to use Qwen with OpenClaw
   - You previously used Qwen OAuth
 title: "Qwen"
 ---
 
-OpenClaw now treats Qwen as a first-class bundled provider with canonical id
-`qwen`. The bundled provider targets the Qwen Cloud / Alibaba DashScope and
+OpenClaw now treats Qwen as a first-class provider plugin with canonical id
+`qwen`. The provider plugin targets the Qwen Cloud / Alibaba DashScope and
 Coding Plan endpoints, keeps legacy `modelstudio` ids working as a compatibility
 alias, and also exposes the Qwen Portal token flow as provider `qwen-oauth`.
 
@@ -22,6 +22,15 @@ If you want `qwen3.6-plus`, prefer the **Standard (pay-as-you-go)** endpoint.
 Coding Plan support can lag behind the public catalog.
 </Tip>
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/qwen-provider
+openclaw gateway restart
+```
+
 ## Getting started
 
 Choose your plan type and follow the setup steps.
@@ -185,7 +194,7 @@ You can override with a custom `baseUrl` in config.
 
 ## Built-in catalog
 
-OpenClaw currently ships this bundled Qwen catalog. The configured catalog is
+OpenClaw currently ships this Qwen static catalog. The configured catalog is
 endpoint-aware: Coding Plan configs omit models that are only known to work on
 the Standard endpoint.
 
@@ -204,12 +213,12 @@ the Standard endpoint.
 
 <Note>
 Availability can still vary by endpoint and billing plan even when a model is
-present in the bundled catalog.
+present in the static catalog.
 </Note>
 
 ## Thinking Controls
 
-For reasoning-enabled Qwen Cloud models, the bundled provider maps OpenClaw
+For reasoning-enabled Qwen Cloud models, the provider maps OpenClaw
 thinking levels to DashScope's top-level `enable_thinking` request flag. Disabled
 thinking sends `enable_thinking: false`; other thinking levels send
 `enable_thinking: true`.
@@ -242,7 +251,7 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov
 
 <AccordionGroup>
   <Accordion title="Image and video understanding">
-    The bundled Qwen plugin registers media understanding for images and video
+    The Qwen plugin registers media understanding for images and video
     on the **Standard** DashScope endpoints (not the Coding Plan endpoints).
 
     | Property      | Value                 |
@@ -267,7 +276,7 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov
     `qwen3.6-plus`, switch to Standard (pay-as-you-go) instead of the Coding Plan
     endpoint/key pair.
 
-    OpenClaw's bundled Qwen catalog does not advertise `qwen3.6-plus` on Coding
+    OpenClaw's Qwen static catalog does not advertise `qwen3.6-plus` on Coding
     Plan endpoints, but explicitly configured `qwen/qwen3.6-plus` entries under
     `models.providers.qwen.models` are honored on Coding Plan baseUrls so you
     can opt that model in if Aliyun enables it on your subscription. The
@@ -279,13 +288,13 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov
     The `qwen` plugin is being positioned as the vendor home for the full Qwen
     Cloud surface, not just coding/text models.
 
-    - **Text/chat models:** bundled now
+    - **Text/chat models:** available through the plugin
     - **Tool calling, structured output, thinking:** inherited from the OpenAI-compatible transport
     - **Image generation:** planned at the provider-plugin layer
-    - **Image/video understanding:** bundled now on the Standard endpoint
+    - **Image/video understanding:** available through the plugin on the Standard endpoint
     - **Speech/audio:** planned at the provider-plugin layer
     - **Memory embeddings/reranking:** planned through the embedding adapter surface
-    - **Video generation:** bundled now through the shared video-generation capability
+    - **Video generation:** available through the plugin through the shared video-generation capability
 
   </Accordion>
 
@@ -300,7 +309,7 @@ See [Video Generation](/tools/video-generation) for shared tool parameters, prov
     Coding Plan or Standard Qwen hosts still keeps video generation on the correct
     regional DashScope video endpoint.
 
-    Current bundled Qwen video-generation limits:
+    Current Qwen video-generation limits:
 
     - Up to **1** output video per request
     - Up to **1** input image

docs/providers/stepfun.md

@@ -6,7 +6,7 @@ read_when:
 title: "StepFun"
 ---
 
-OpenClaw includes a bundled StepFun provider plugin with two provider ids:
+The StepFun provider plugin supports two provider ids:
 
 - `stepfun` for the standard endpoint
 - `stepfun-plan` for the Step Plan endpoint
@@ -15,6 +15,15 @@ OpenClaw includes a bundled StepFun provider plugin with two provider ids:
 Standard and Step Plan are **separate providers** with different endpoints and model ref prefixes (`stepfun/...` vs `stepfun-plan/...`). Use a China key with the `.com` endpoints and a global key with the `.ai` endpoints.
 </Warning>
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/stepfun-provider
+openclaw gateway restart
+```
+
 ## Region and endpoint overview
 
 | Endpoint  | China (`.com`)                         | Global (`.ai`)                        |
@@ -199,7 +208,7 @@ Choose your provider surface and follow the setup steps.
   </Accordion>
 
   <Accordion title="Notes">
-    - The provider is bundled with OpenClaw, so there is no separate plugin install step.
+    - The provider is an official external package; install it before setup.
     - `step-3.5-flash-2603` is currently exposed only on `stepfun-plan`.
     - A single auth flow writes region-matched profiles for both `stepfun` and `stepfun-plan`, so both surfaces can be discovered together.
     - Use `openclaw models list` and `openclaw models set <provider/model>` to inspect or switch models.

docs/refactor/database-first.md

@@ -89,7 +89,7 @@ This migration has one canonical runtime shape:
   indexing helpers live on `memory-core-host-engine-session-transcripts`; any
   QMD re-export is compatibility only and must not be used by runtime code.
 - Built-in memory indexes live in the owning agent database. Runtime config and
-  resolved runtime contracts must not expose `memorySearch.store.path`; doctor
+  resolved runtime contracts must not expose `memory.search.store.path`; doctor
   deletes that legacy config key and current code passes the agent
   `databasePath` internally.
 
@@ -382,15 +382,16 @@ The branch already has a real shared SQLite base:
   exact transcript event row.
 - Memory-core indexes now use explicit agent-database tables
   `memory_index_meta`, `memory_index_sources`, `memory_index_chunks`, and
-  `memory_embedding_cache`; optional FTS/vector side indexes use the same
-  `memory_index_*` prefix instead of generic `meta`, `files`, `chunks`, or
-  `chunks_vec` tables. `memory_index_sources` is keyed by
-  `(source_kind, source_key)` and carries optional `session_id` ownership, so
-  session-derived sources and chunks cascade when a session is deleted. Cached
-  chunk embeddings are stored as Float32 SQLite BLOBs, not JSON text arrays.
-  These tables are derived/search cache, not canonical transcript storage; they
-  can be deleted and rebuilt from `sessions`, `transcript_events`, and memory
-  workspace files.
+  `memory_embedding_cache`, with `memory_index_state` tracking revision changes.
+  Optional FTS/vector side indexes are named `memory_index_chunks_fts` and
+  `memory_index_chunks_vec` instead of generic `meta`, `files`, `chunks`,
+  `chunks_fts`, or `chunks_vec` tables. The canonical names retain the current
+  path/source row shape and serialized embedding compatibility. These tables
+  are derived/search cache, not canonical transcript storage; they can be
+  deleted and rebuilt from memory workspace files and configured sources.
+  Opening a shipped generic-name memory index migrates its metadata, sources,
+  chunks, and embedding cache into the canonical tables; derived FTS/vector
+  tables are rebuilt under their canonical names.
 - Subagent run recovery state now lives in typed shared `subagent_runs` rows
   with indexed child, requester, and controller session keys. The old
   `subagents/runs.json` file is doctor migration input only.
@@ -878,9 +879,9 @@ sessionId}` and session key context.
 - Plugin runtime no longer exposes `api.runtime.agent.session.resolveTranscriptLocatorPath`;
   plugin code uses SQLite row helpers and scope values.
 - The public `session-store-runtime` SDK surface now only exports session row
-  and transcript row helpers. Raw SQLite database open/path and close/reset
-  helpers live in the focused `sqlite-runtime` SDK surface, so plugin tests no
-  longer pull the deprecated broad testing barrel for database cleanup.
+  and transcript row helpers. Focused SQLite schema/path/transaction helpers
+  live in `sqlite-runtime`; raw open/close/reset helpers remain local-only for
+  first-party tests.
 - Legacy `.jsonl` trajectory/checkpoint filename classifiers now live in the
   doctor legacy session-file module. Core session validation no longer imports
   file-artifact helpers to decide normal SQLite session ids.
@@ -1389,7 +1390,7 @@ create` validates the written archive by default; `--no-verify` is the
   `ensureOpenClawModelCatalog`; there is no `models.json` compatibility API in
   runtime code. The implementation writes SQLite and the embedded PI registry is
   hydrated from that stored payload without creating a `models.json` file.
-- QMD session transcript markdown export and `memory.qmd.sessions` config were
+- QMD session transcript markdown export and `agents.defaults.memory.qmd.sessions` config were
   removed. There is no QMD transcript collection, no `qmd/sessions*` runtime
   path, and no file-backed session memory bridge.
 - Memory-core runtime imports SQLite transcript indexing helpers from
@@ -1491,10 +1492,11 @@ vfs_entries(namespace, path, kind, content_blob, metadata_json, updated_at)
 tool_artifacts(run_id, artifact_id, kind, metadata_json, blob, created_at)
 run_artifacts(run_id, path, kind, metadata_json, blob, created_at)
 trajectory_runtime_events(session_id, run_id, seq, event_json, created_at)
-memory_index_meta(meta_key, schema_version, provider, model, provider_key, sources_json, scope_hash, chunk_tokens, chunk_overlap, vector_dims, fts_tokenizer, config_hash, updated_at)
-memory_index_sources(source_kind, source_key, path, session_id, hash, mtime, size)
-memory_index_chunks(id, source_kind, source_key, path, session_id, start_line, end_line, hash, model, text, embedding, embedding_dims, updated_at)
+memory_index_meta(key, value)
+memory_index_sources(path, source, hash, mtime, size)
+memory_index_chunks(id, path, source, start_line, end_line, hash, model, text, embedding, updated_at)
 memory_embedding_cache(provider, model, provider_key, hash, embedding, dims, updated_at)
+memory_index_state(id, revision)
 cache_entries(scope, key, value_json, blob, expires_at, updated_at)
 ```
 
@@ -1555,7 +1557,7 @@ Move these into the global database:
   `plugin-state/state.sqlite` sidecar importer is deleted.
 - Builtin memory search no longer defaults to `memory/<agentId>.sqlite`; its
   index tables live in the owning agent database, and the explicit
-  `memorySearch.store.path` sidecar opt-in has been retired to doctor config
+  `memory.search.store.path` sidecar opt-in has been retired to doctor config
   migration.
 - Builtin memory reindex resets only memory-owned tables in the agent database.
   It must not replace the whole SQLite file, because the same database owns
@@ -1722,9 +1724,12 @@ Keep shared coordination state in `state/openclaw.sqlite`:
   `media_blobs` and removes the source files after successful row writes.
 - Debug proxy capture sessions, events, and payload blobs. Done: captures live
   in the shared state DB and open through the shared state DB bootstrap, schema,
-  WAL, and busy-timeout settings. There is no debug proxy runtime sidecar DB
-  override, blob directory, or proxy-capture-only generated schema/codegen
-  target.
+  WAL, and busy-timeout settings. Payload bytes are gzip-compressed in
+  `capture_blobs.data`; there is no debug proxy runtime sidecar DB override,
+  blob directory, or proxy-capture-only generated schema/codegen target.
+  Doctor/startup migration imports shipped `debug-proxy/capture.sqlite` rows
+  and referenced payload blobs, including active legacy DB/blob environment
+  overrides, then archives those sources while leaving CA certificates intact.
 
 This phase also deletes duplicate sidecar openers, permission helpers, WAL
 setup, filesystem pruning, and compatibility writers from those subsystems.
@@ -1885,7 +1890,7 @@ verified extracted payload.
    - Move Task Flow tables into the global database. Done for runtime writes;
      the unshipped legacy sidecar importer is deleted.
    - Move builtin memory-search tables into each agent database. Done; explicit
-     custom `memorySearch.store.path` is now removed by doctor config migration.
+     custom `memory.search.store.path` is now removed by doctor config migration.
      Full reindex runs in place against memory tables only; the old whole-file
      swap path and sidecar index swap helper are deleted.
    - Delete duplicate database openers, WAL setup, permission helpers, and

docs/reference/api-usage-costs.md

@@ -66,7 +66,7 @@ OpenClaw can pick up credentials from:
 - **Auth profiles** (per-agent, stored in `auth-profiles.json`).
 - **Environment variables** (e.g. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
 - **Config** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`,
-  `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`,
+  `plugins.entries.firecrawl.config.webFetch.apiKey`, `memory.search.*`,
   `talk.providers.*.apiKey`).
 - **Skills** (`skills.entries.<name>.apiKey`) which may export keys to the skill process env.
 
@@ -113,16 +113,16 @@ and [Models](/concepts/models).
 
 Semantic memory search uses **embedding APIs** when configured for remote providers:
 
-- `memorySearch.provider = "openai"` → OpenAI embeddings
-- `memorySearch.provider = "gemini"` → Gemini embeddings
-- `memorySearch.provider = "voyage"` → Voyage embeddings
-- `memorySearch.provider = "mistral"` → Mistral embeddings
-- `memorySearch.provider = "deepinfra"` → DeepInfra embeddings
-- `memorySearch.provider = "lmstudio"` → LM Studio embeddings (local/self-hosted)
-- `memorySearch.provider = "ollama"` → Ollama embeddings (local/self-hosted; typically no hosted API billing)
+- `memory.search.provider = "openai"` → OpenAI embeddings
+- `memory.search.provider = "gemini"` → Gemini embeddings
+- `memory.search.provider = "voyage"` → Voyage embeddings
+- `memory.search.provider = "mistral"` → Mistral embeddings
+- `memory.search.provider = "deepinfra"` → DeepInfra embeddings
+- `memory.search.provider = "lmstudio"` → LM Studio embeddings (local/self-hosted)
+- `memory.search.provider = "ollama"` → Ollama embeddings (local/self-hosted; typically no hosted API billing)
 - Optional fallback to a remote provider if local embeddings fail
 
-You can keep it local with `memorySearch.provider = "local"` (no API usage).
+You can keep it local with `memory.search.provider = "local"` (no API usage).
 
 See [Memory](/concepts/memory).
 
@@ -154,7 +154,8 @@ See [Web tools](/tools/web).
 
 ### 5) Web fetch tool (Firecrawl)
 
-`web_fetch` can call **Firecrawl** when an API key is present:
+`web_fetch` can call **Firecrawl** with keyless starter access. Add an API key
+for higher limits:
 
 - `FIRECRAWL_API_KEY` or `plugins.entries.firecrawl.config.webFetch.apiKey`
 

docs/reference/memory-config.md

@@ -29,10 +29,11 @@ This page lists every configuration knob for OpenClaw memory search. For concept
   </Card>
 </CardGroup>
 
-All memory search settings live under `agents.defaults.memorySearch` in `openclaw.json` unless noted otherwise.
+Memory settings live under `agents.defaults.memory` in `openclaw.json`. Agent
+entries can override the same shape at `agents.list[].memory`.
 
 <Note>
-If you are looking for the **active memory** feature toggle and sub-agent config, that lives under `plugins.entries.active-memory` instead of `memorySearch`.
+If you are looking for the **active memory** feature toggle and sub-agent config, that lives under `plugins.entries.active-memory` instead of `memory.search`.
 
 Active memory uses a two-gate model:
 
@@ -71,7 +72,8 @@ When `provider` is unset, legacy `provider: "auto"` is present, or
 `provider: "none"` intentionally selects FTS-only mode, memory recall can still
 use lexical FTS ranking when embeddings are unavailable.
 
-Explicit non-local providers fail closed. If you set `memorySearch.provider` to
+Explicit non-local providers fail closed. If you set
+`agents.defaults.memory.search.provider` to
 a concrete remote-backed provider such as OpenAI, Gemini, Voyage, Mistral,
 Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio, or an OpenAI-compatible
 custom provider, and that provider is unavailable at runtime, `memory_search`
@@ -81,7 +83,13 @@ provider/auth configuration, switch to a reachable provider, or set
 
 ### Custom provider ids
 
-`memorySearch.provider` can point at a custom `models.providers.<id>` entry for memory-specific provider adapters such as `ollama`, or for OpenAI-compatible model APIs such as `openai-responses` / `openai-completions`. OpenClaw resolves that provider's `api` owner for the embedding adapter while preserving the custom provider id for endpoint, auth, and model-prefix handling. This lets multi-GPU or multi-host setups dedicate memory embeddings to a specific local endpoint:
+`agents.defaults.memory.search.provider` can point at a custom
+`models.providers.<id>` entry for memory-specific provider adapters such as
+`ollama`, or for OpenAI-compatible model APIs such as `openai-responses` /
+`openai-completions`. OpenClaw resolves that provider's `api` owner for the
+embedding adapter while preserving the custom provider id for endpoint, auth,
+and model-prefix handling. This lets multi-GPU or multi-host setups dedicate
+memory embeddings to a specific local endpoint:
 
 ```json5
 {
@@ -97,9 +105,11 @@ provider/auth configuration, switch to a reachable provider, or set
   },
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "ollama-5080",
-        model: "qwen3-embedding:0.6b",
+      memory: {
+        search: {
+          provider: "ollama-5080",
+          model: "qwen3-embedding:0.6b",
+        },
       },
     },
   },
@@ -146,12 +156,14 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible
 {
   agents: {
     defaults: {
-      memorySearch: {
-        provider: "openai-compatible",
-        model: "text-embedding-3-small",
-        remote: {
-          baseUrl: "https://api.example.com/v1/",
-          apiKey: "YOUR_KEY",
+      memory: {
+        search: {
+          provider: "openai-compatible",
+          model: "text-embedding-3-small",
+          remote: {
+            baseUrl: "https://api.example.com/v1/",
+            apiKey: "YOUR_KEY",
+          },
         },
       },
     },
@@ -189,15 +201,17 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible
     {
       agents: {
         defaults: {
-          memorySearch: {
-            provider: "openai-compatible",
-            remote: {
-              baseUrl: "https://embeddings.example/v1",
-              apiKey: "${EMBEDDINGS_API_KEY}",
+          memory: {
+            search: {
+              provider: "openai-compatible",
+              remote: {
+                baseUrl: "https://embeddings.example/v1",
+                apiKey: "${EMBEDDINGS_API_KEY}",
+              },
+              model: "asymmetric-embedder",
+              queryInputType: "query",
+              documentInputType: "passage",
             },
-            model: "asymmetric-embedder",
-            queryInputType: "query",
-            documentInputType: "passage",
           },
         },
       },
@@ -216,9 +230,11 @@ Use `provider: "openai-compatible"` for a generic OpenAI-compatible
     {
       agents: {
         defaults: {
-          memorySearch: {
-            provider: "bedrock",
-            model: "amazon.titan-embed-text-v2:0",
+          memory: {
+            search: {
+              provider: "bedrock",
+              model: "amazon.titan-embed-text-v2:0",
+            },
           },
         },
       },
@@ -308,7 +324,7 @@ Unset uses the provider default: 600 seconds for local/self-hosted providers suc
 
 ## Hybrid search config
 
-All under `memorySearch.query.hybrid`:
+All under `agents.defaults.memory.search.query.hybrid`:
 
 | Key                   | Type      | Default | Description                        |
 | --------------------- | --------- | ------- | ---------------------------------- |
@@ -341,13 +357,15 @@ All under `memorySearch.query.hybrid`:
 {
   agents: {
     defaults: {
-      memorySearch: {
-        query: {
-          hybrid: {
-            vectorWeight: 0.7,
-            textWeight: 0.3,
-            mmr: { enabled: true, lambda: 0.7 },
-            temporalDecay: { enabled: true, halfLifeDays: 30 },
+      memory: {
+        search: {
+          query: {
+            hybrid: {
+              vectorWeight: 0.7,
+              textWeight: 0.3,
+              mmr: { enabled: true, lambda: 0.7 },
+              temporalDecay: { enabled: true, halfLifeDays: 30 },
+            },
           },
         },
       },
@@ -368,8 +386,10 @@ All under `memorySearch.query.hybrid`:
 {
   agents: {
     defaults: {
-      memorySearch: {
-        extraPaths: ["../team-docs", "/srv/shared-notes"],
+      memory: {
+        search: {
+          extraPaths: ["../team-docs", "/srv/shared-notes"],
+        },
       },
     },
   },
@@ -378,7 +398,14 @@ All under `memorySearch.query.hybrid`:
 
 Paths can be absolute or workspace-relative. Directories are scanned recursively for `.md` files. Symlink handling depends on the active backend: the builtin engine ignores symlinks, while QMD follows the underlying QMD scanner behavior.
 
-For agent-scoped cross-agent transcript search, use `agents.list[].memorySearch.qmd.extraCollections` instead of `memory.qmd.paths`. Those extra collections follow the same `{ path, name, pattern? }` shape, but they are merged per agent and can preserve explicit shared names when the path points outside the current workspace. If the same resolved path appears in both `memory.qmd.paths` and `memorySearch.qmd.extraCollections`, QMD keeps the first entry and skips the duplicate.
+For agent-scoped cross-agent transcript search, use
+`agents.list[].memory.search.qmd.extraCollections` instead of
+`agents.defaults.memory.qmd.paths`. Those extra collections follow the same
+`{ path, name, pattern? }` shape, but they are merged per agent and can preserve
+explicit shared names when the path points outside the current workspace. If the
+same resolved path appears in both `agents.defaults.memory.qmd.paths` and
+`agents.defaults.memory.search.qmd.extraCollections`, QMD keeps the first entry
+and skips the duplicate.
 
 ---
 
@@ -460,16 +487,18 @@ When sqlite-vec is unavailable, OpenClaw falls back to in-process cosine similar
 
 ## Index storage
 
-| Key                   | Type     | Default                               | Description                                 |
-| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
-| `store.path`          | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Index location (supports `{agentId}` token) |
-| `store.fts.tokenizer` | `string` | `unicode61`                           | FTS5 tokenizer (`unicode61` or `trigram`)   |
+Built-in memory indexes live in each agent's OpenClaw SQLite database at
+`agents/<agentId>/agent/openclaw-agent.sqlite`.
+
+| Key                   | Type     | Default     | Description                               |
+| --------------------- | -------- | ----------- | ----------------------------------------- |
+| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer (`unicode61` or `trigram`) |
 
 ---
 
 ## QMD backend config
 
-Set `memory.backend = "qmd"` to enable. All QMD settings live under `memory.qmd`:
+Set `agents.defaults.memory.backend = "qmd"` to enable. All QMD settings live under `agents.defaults.memory.qmd`:
 
 | Key                      | Type      | Default  | Description                                                                           |
 | ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- |
@@ -520,11 +549,15 @@ QMD model overrides stay on the QMD side, not OpenClaw config. If you need to ov
 
     ```json5
     {
-      memory: {
-        qmd: {
-          scope: {
-            default: "deny",
-            rules: [{ action: "allow", match: { chatType: "direct" } }],
+      agents: {
+        defaults: {
+          memory: {
+            qmd: {
+              scope: {
+                default: "deny",
+                rules: [{ action: "allow", match: { chatType: "direct" } }],
+              },
+            },
           },
         },
       },
@@ -537,7 +570,7 @@ QMD model overrides stay on the QMD side, not OpenClaw config. If you need to ov
 
   </Accordion>
   <Accordion title="Citations">
-    `memory.citations` applies to all backends:
+    `agents.defaults.memory.citations` applies to all backends:
 
     | Value            | Behavior                                            |
     | ---------------- | --------------------------------------------------- |
@@ -554,18 +587,22 @@ When gateway-start QMD initialization is enabled, OpenClaw starts QMD only for e
 
 ```json5
 {
-  memory: {
-    backend: "qmd",
-    citations: "auto",
-    qmd: {
-      includeDefaultMemory: true,
-      update: { interval: "5m", debounceMs: 15000 },
-      limits: { maxResults: 6, timeoutMs: 4000 },
-      scope: {
-        default: "deny",
-        rules: [{ action: "allow", match: { chatType: "direct" } }],
+  agents: {
+    defaults: {
+      memory: {
+        backend: "qmd",
+        citations: "auto",
+        qmd: {
+          includeDefaultMemory: true,
+          update: { interval: "5m", debounceMs: 15000 },
+          limits: { maxResults: 6, timeoutMs: 4000 },
+          scope: {
+            default: "deny",
+            rules: [{ action: "allow", match: { chatType: "direct" } }],
+          },
+          paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
+        },
       },
-      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
     },
   },
 }
@@ -575,9 +612,10 @@ When gateway-start QMD initialization is enabled, OpenClaw starts QMD only for e
 
 ## Dreaming
 
-Dreaming is configured under `plugins.entries.memory-core.config.dreaming`, not under `agents.defaults.memorySearch`.
+Dreaming is configured under `agents.defaults.memory.extensions.memory-core.dreaming`, not under `agents.defaults.memory.search`.
 
-Dreaming runs as one scheduled sweep and uses internal light/deep/REM phases as an implementation detail.
+Each enabled agent gets its own scheduled dreaming sweep. The sweep uses
+internal light/deep/REM phases as an implementation detail.
 
 For conceptual behavior and slash commands, see [Dreaming](/concepts/dreaming).
 
@@ -590,22 +628,26 @@ For conceptual behavior and slash commands, see [Dreaming](/concepts/dreaming).
 | `model`                                | `string`  | default model | Optional Dream Diary subagent model override                                                                                     |
 | `phases.deep.maxPromotedSnippetTokens` | `number`  | `160`         | Maximum estimated tokens kept from each short-term recall snippet promoted into `MEMORY.md`; provenance metadata remains visible |
 
-### Example
+### Per-agent dreaming control
+
+Dreaming is resolved per agent. An agent can opt out with
+`agents.list[].memory.extensions.memory-core.dreaming.enabled = false`:
 
 ```json5
 {
-  plugins: {
-    entries: {
-      "memory-core": {
-        subagent: {
-          allowModelOverride: true,
-          allowedModels: ["anthropic/claude-sonnet-4-6"],
-        },
-        config: {
-          dreaming: {
-            enabled: true,
-            frequency: "0 3 * * *",
-            model: "anthropic/claude-sonnet-4-6",
+  agents: {
+    list: [
+      { id: "main", memory: { extensions: { "memory-core": { dreaming: { enabled: false } } } } },
+      { id: "oracle", memory: { extensions: { "memory-core": { dreaming: { enabled: false } } } } },
+      { id: "librarian" },
+    ],
+    defaults: {
+      memory: {
+        extensions: {
+          "memory-core": {
+            dreaming: {
+              enabled: true,
+            },
           },
         },
       },
@@ -614,9 +656,47 @@ For conceptual behavior and slash commands, see [Dreaming](/concepts/dreaming).
 }
 ```
 
+In this example, `main` and `oracle` will not get cron jobs, while `librarian`
+inherits the enabled default.
+
+### Example
+
+```json5
+{
+  agents: {
+    defaults: {
+      memory: {
+        extensions: {
+          "memory-core": {
+            dreaming: {
+              enabled: true,
+              frequency: "0 3 * * *",
+              model: "anthropic/claude-sonnet-4-6",
+            },
+          },
+        },
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      "memory-core": {
+        subagent: {
+          allowModelOverride: true,
+          allowedModels: ["anthropic/claude-sonnet-4-6"],
+        },
+      },
+    },
+  },
+}
+```
+
 <Note>
-- Dreaming writes machine state to `memory/.dreams/`.
-- Dreaming writes human-readable narrative output to `DREAMS.md` (or existing `dreams.md`).
+  - Dreaming writes agent-private state and artifacts to
+    `memory/.dreams/agents/<agent-id>/`; normal memory search does not index
+    this directory.
+  - Dreaming writes each agent's human-readable narrative output to
+    `memory/.dreams/agents/<agent-id>/DREAMS.md`.
 - `dreaming.model` uses the existing plugin subagent trust gate; set `plugins.entries.memory-core.subagent.allowModelOverride: true` before enabling it.
 - Dream Diary retries once with the session default model when the configured model is unavailable. Trust or allowlist failures are logged and are not silently retried.
 - The light/deep/REM phase policy and thresholds are internal behavior, not user-facing config.

docs/reference/secretref-credential-surface.md

@@ -34,9 +34,9 @@ Scope intent:
 - `models.providers.*.request.tls.key`
 - `models.providers.*.request.tls.passphrase`
 - `skills.entries.*.apiKey`
-- `agents.defaults.memorySearch.remote.apiKey`
+- `agents.defaults.memory.search.remote.apiKey`
 - `agents.list[].tts.providers.*.apiKey`
-- `agents.list[].memorySearch.remote.apiKey`
+- `agents.list[].memory.search.remote.apiKey`
 - `talk.providers.*.apiKey`
 - `talk.realtime.providers.*.apiKey`
 - `messages.tts.providers.*.apiKey`

docs/reference/secretref-user-supplied-credentials-matrix.json

@@ -16,16 +16,16 @@
   ],
   "entries": [
     {
-      "id": "agents.defaults.memorySearch.remote.apiKey",
+      "id": "agents.defaults.memory.search.remote.apiKey",
       "configFile": "openclaw.json",
-      "path": "agents.defaults.memorySearch.remote.apiKey",
+      "path": "agents.defaults.memory.search.remote.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },
     {
-      "id": "agents.list[].memorySearch.remote.apiKey",
+      "id": "agents.list[].memory.search.remote.apiKey",
       "configFile": "openclaw.json",
-      "path": "agents.list[].memorySearch.remote.apiKey",
+      "path": "agents.list[].memory.search.remote.apiKey",
       "secretShape": "secret_input",
       "optIn": true
     },

docs/tools/exa-search.md

@@ -11,6 +11,15 @@ OpenClaw supports [Exa AI](https://exa.ai/) as a `web_search` provider. Exa
 offers neural, keyword, and hybrid search modes with built-in content
 extraction (highlights, text, summaries).
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/exa-plugin
+openclaw gateway restart
+```
+
 ## Get an API key
 
 <Steps>

docs/tools/firecrawl.md

@@ -2,7 +2,8 @@
 summary: "Firecrawl search, scrape, and web_fetch fallback"
 read_when:
   - You want Firecrawl-backed web extraction
-  - You need a Firecrawl API key
+  - You want keyless Firecrawl web_fetch
+  - You need a Firecrawl API key for search or higher limits
   - You want Firecrawl as a web_search provider
   - You want anti-bot extraction for web_fetch
 title: "Firecrawl"
@@ -17,10 +18,21 @@ OpenClaw can use **Firecrawl** in three ways:
 It is a hosted extraction/search service that supports bot circumvention and caching,
 which helps with JS-heavy sites or pages that block plain HTTP fetches.
 
-## Get an API key
+## Install plugin
 
-1. Create a Firecrawl account and generate an API key.
-2. Store it in config or set `FIRECRAWL_API_KEY` in the gateway environment.
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/firecrawl-plugin
+openclaw gateway restart
+```
+
+## Keyless web_fetch and API keys
+
+The explicitly selected hosted Firecrawl `web_fetch` fallback supports starter
+access without an API key. Add `FIRECRAWL_API_KEY` in the gateway environment
+or configure it when you need higher limits. Firecrawl `web_search` and
+`firecrawl_scrape` require an API key.
 
 ## Configure Firecrawl search
 
@@ -51,23 +63,29 @@ which helps with JS-heavy sites or pages that block plain HTTP fetches.
 
 Notes:
 
-- Choosing Firecrawl in onboarding or `openclaw configure --section web` enables the bundled Firecrawl plugin automatically.
+- Choosing Firecrawl in onboarding or `openclaw configure --section web` enables the installed Firecrawl plugin automatically.
 - `web_search` with Firecrawl supports `query` and `count`.
 - For Firecrawl-specific controls like `sources`, `categories`, or result scraping, use `firecrawl_search`.
 - `baseUrl` defaults to hosted Firecrawl at `https://api.firecrawl.dev`. Self-hosted overrides are allowed only for private/internal endpoints; HTTP is accepted only for those private targets.
 - `FIRECRAWL_BASE_URL` is the shared env fallback for Firecrawl search and scrape base URLs.
 
-## Configure Firecrawl scrape + web_fetch fallback
+## Configure Firecrawl web_fetch fallback
 
 ```json5
 {
+  tools: {
+    web: {
+      fetch: {
+        provider: "firecrawl", // explicit selection enables keyless fallback
+      },
+    },
+  },
   plugins: {
     entries: {
       firecrawl: {
         enabled: true,
         config: {
           webFetch: {
-            apiKey: "FIRECRAWL_API_KEY_HERE",
             baseUrl: "https://api.firecrawl.dev",
             onlyMainContent: true,
             maxAgeMs: 172800000,
@@ -82,13 +100,15 @@ Notes:
 
 Notes:
 
-- Firecrawl fallback attempts run only when an API key is available (`plugins.entries.firecrawl.config.webFetch.apiKey` or `FIRECRAWL_API_KEY`).
+- The explicitly selected Firecrawl `web_fetch` fallback works without an API key. When configured, OpenClaw sends `plugins.entries.firecrawl.config.webFetch.apiKey` or `FIRECRAWL_API_KEY` for higher limits.
+- Choosing Firecrawl during onboarding or `openclaw configure --section web` enables the plugin and selects Firecrawl for `web_fetch` unless another fetch provider is already configured.
+- `firecrawl_scrape` requires an API key.
 - `maxAgeMs` controls how old cached results can be (ms). Default is 2 days.
 - Legacy `tools.web.fetch.firecrawl.*` config is auto-migrated by `openclaw doctor --fix`.
 - Firecrawl scrape/base URL overrides follow the same hosted/private rule as search: public hosted traffic uses `https://api.firecrawl.dev`; self-hosted overrides must resolve to private/internal endpoints.
 - `firecrawl_scrape` rejects obvious private, loopback, metadata, and non-HTTP(S) target URLs before forwarding them to Firecrawl, matching the `web_fetch` target-safety contract for explicit Firecrawl scrape calls.
 
-`firecrawl_scrape` reuses the same `plugins.entries.firecrawl.config.webFetch.*` settings and env vars.
+`firecrawl_scrape` reuses the same `plugins.entries.firecrawl.config.webFetch.*` settings and env vars, including its required API key.
 
 ### Self-hosted Firecrawl
 
@@ -141,12 +161,12 @@ than basic-only scraping.
 `web_fetch` extraction order:
 
 1. Readability (local)
-2. Firecrawl (if selected or auto-detected as the active web-fetch fallback)
+2. Firecrawl (when selected, or auto-detected from configured credentials)
 3. Basic HTML cleanup (last fallback)
 
 The selection knob is `tools.web.fetch.provider`. If you omit it, OpenClaw
 auto-detects the first ready web-fetch provider from available credentials.
-Today the bundled provider is Firecrawl.
+The official Firecrawl plugin provides that fallback.
 
 ## Related
 

docs/tools/image-generation.md

@@ -494,6 +494,23 @@ openclaw infer image generate \
   --json
 ```
 
+  </Tab>
+  <Tab title="Generate (OpenAI low quality)">
+```text
+/tool image_generate action=generate model=openai/gpt-image-2 prompt="Low-cost draft poster for a quiet productivity app" quality=low openai='{"moderation":"low"}'
+```
+
+Equivalent CLI:
+
+```bash
+openclaw infer image generate \
+  --model openai/gpt-image-2 \
+  --quality low \
+  --openai-moderation low \
+  --prompt "Low-cost draft poster for a quiet productivity app" \
+  --json
+```
+
   </Tab>
   <Tab title="Generate (two square)">
 ```text
@@ -517,11 +534,11 @@ openclaw infer image generate \
   </Tab>
 </Tabs>
 
-The same `--output-format` and `--background` flags are available on
-`openclaw infer image edit`; `--openai-background` remains as an
-OpenAI-specific alias. Bundled providers other than OpenAI do not declare
-explicit background control today, so `background: "transparent"` is reported
-as ignored for them.
+The same `--output-format`, `--background`, `--quality`, and
+`--openai-moderation` flags are available on `openclaw infer image edit`;
+`--openai-background` remains as an OpenAI-specific alias. Bundled providers
+other than OpenAI do not declare explicit background control today, so
+`background: "transparent"` is reported as ignored for them.
 
 ## Related
 

docs/tools/parallel-search.md

@@ -7,7 +7,7 @@ read_when:
 title: "Parallel search"
 ---
 
-OpenClaw bundles two [Parallel](https://parallel.ai/) `web_search` providers:
+The Parallel plugin provides two [Parallel](https://parallel.ai/) `web_search` providers:
 
 - **Parallel Search (Free)** (`parallel-free`) -- Parallel's free
   [Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp). Requires no
@@ -27,6 +27,15 @@ explicitly.
   through Parallel.
 </Note>
 
+## Install plugin
+
+Install the official plugin, then restart Gateway:
+
+```bash
+openclaw plugins install @openclaw/parallel-plugin
+openclaw gateway restart
+```
+
 ## API key (paid provider)
 
 `parallel-free` requires no API key, but it still must be selected as the