docs(codex): document native compaction hooks

Clarify Codex hook layering in the harness docs.

.agents/skills/blacksmith-testbox/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: blacksmith-testbox
-description: >
-  Validate code changes against real CI when local execution is not
-  enough. Use for CI-parity checks, secrets/services, migrations, or
-  builds/tests that cannot run reliably on the local machine. Do not
-  replace repo-documented local test/build loops just because this
-  skill exists.
+description: Run Blacksmith Testbox for CI-parity checks, secrets, hosted services, migrations, or builds local cannot reproduce.
 ---
 
 # Blacksmith Testbox

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

@@ -1,6 +1,6 @@
 ---
 name: openclaw-ghsa-maintainer
-description: Maintainer workflow for OpenClaw GitHub Security Advisories (GHSA). Use when Codex needs to inspect, patch, validate, or publish a repo advisory, verify private-fork state, prepare advisory Markdown or JSON payloads safely, handle GHSA API-specific publish constraints, or confirm advisory publish success.
+description: Inspect, patch, validate, publish, or confirm OpenClaw GHSA security advisories and private-fork state.
 ---
 
 # OpenClaw GHSA Maintainer

.agents/skills/openclaw-parallels-smoke/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-parallels-smoke
-description: End-to-end Parallels smoke, upgrade, and rerun workflow for OpenClaw across macOS, Windows, and Linux guests. Use when Codex needs to run, rerun, debug, or interpret VM-based install, onboarding, gateway smoke tests, latest-release-to-main upgrade checks, fresh snapshot retests, or optional Discord roundtrip verification under Parallels.
+description: Run, rerun, debug, or interpret OpenClaw Parallels install, onboarding, gateway smoke, and upgrade checks.
 ---
 
 # OpenClaw Parallels Smoke

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

@@ -1,6 +1,6 @@
 ---
 name: openclaw-pr-maintainer
-description: Maintainer workflow for reviewing, triaging, preparing, closing, or landing OpenClaw pull requests and related issues. Use when Codex needs to validate bug-fix claims, search for related issues or PRs, apply or recommend close/reason labels, prepare GitHub comments safely, check review-thread follow-up, or perform maintainer-style PR decision making before merge or closure.
+description: Review, triage, close, label, comment on, or land OpenClaw PRs/issues with maintainer evidence checks.
 ---
 
 # OpenClaw PR Maintainer

.agents/skills/openclaw-qa-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-qa-testing
-description: Run, watch, debug, and extend OpenClaw QA testing with qa-lab and qa-channel. Use when Codex needs to execute the repo-backed QA suite, inspect live QA artifacts, debug failing scenarios, add new QA scenarios, or explain the OpenClaw QA workflow. Prefer the live OpenAI lane with regular openai/gpt-5.4 in fast mode; do not use gpt-5.4-pro or gpt-5.4-mini unless the user explicitly overrides that policy.
+description: Run, watch, debug, extend, or explain OpenClaw qa-lab and qa-channel scenarios, artifacts, and live lanes.
 ---
 
 # OpenClaw QA Testing

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

@@ -1,6 +1,6 @@
 ---
 name: openclaw-release-maintainer
-description: Maintainer workflow for OpenClaw releases, prereleases, changelog release notes, and publish validation. Use when Codex needs to prepare or verify stable or beta release steps, align version naming, assemble release notes, check release auth requirements, or validate publish-time commands and artifacts.
+description: Prepare or verify OpenClaw stable/beta releases, changelogs, release notes, publish commands, and artifacts.
 ---
 
 # OpenClaw Release Maintainer

.agents/skills/openclaw-secret-scanning-maintainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-secret-scanning-maintainer
-description: Maintainer-only workflow for handling GitHub Secret Scanning alerts on OpenClaw. Use when Codex needs to triage, redact, clean up, and resolve secret leakage found in issue comments, issue bodies, PR comments, or other GitHub content.
+description: Triage, redact, clean up, and resolve OpenClaw GitHub Secret Scanning alerts in issues or PRs.
 ---
 
 # OpenClaw Secret Scanning Maintainer

.agents/skills/openclaw-test-heap-leaks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-test-heap-leaks
-description: Investigate `pnpm test` memory growth, Vitest worker OOMs, and suspicious RSS increases in OpenClaw using the `scripts/test-parallel.mjs` heap snapshot tooling. Use when Codex needs to reproduce test-lane memory growth, collect repeated `.heapsnapshot` files, compare snapshots from the same worker PID, triage likely transformed-module retention versus likely runtime leaks, and fix or reduce the impact by patching cleanup logic or isolating hotspot tests.
+description: Investigate OpenClaw pnpm test memory growth, Vitest OOMs, RSS spikes, and heap snapshot deltas.
 ---
 
 # OpenClaw Test Heap Leaks

.agents/skills/openclaw-test-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openclaw-test-performance
-description: Benchmark, diagnose, and optimize OpenClaw test performance without losing coverage. Use when Codex needs to reassess `pnpm test`, compare grouped Vitest reports, identify CPU/memory/import hotspots, fix slow tests or cold runtime paths, preserve behavior proofs, update the performance report, add AGENTS guardrails, and make scoped commits/pushes for OpenClaw test-speed work.
+description: Benchmark, diagnose, and optimize OpenClaw test runtime, import hotspots, CPU/RSS, and slow coverage paths.
 ---
 
 # OpenClaw Test Performance

.agents/skills/optimizetests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: optimizetests
-description: Optimize OpenClaw test runtime end to end. Use when the user asks for /optimizetests, slow-test review, import optimization, deduping tests, moving misplaced core coverage to extensions, or reducing CI/test wall time without adding shards or dropping coverage.
+description: Optimize OpenClaw slow tests, imports, misplaced coverage, and CI wall time without dropping coverage.
 ---
 
 # Optimize Tests

.agents/skills/parallels-discord-roundtrip/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parallels-discord-roundtrip
-description: Run the macOS Parallels smoke harness with Discord end-to-end roundtrip verification, including guest send, host verification, host reply, and guest readback.
+description: Run macOS Parallels smoke with Discord send, host verification, host reply, and guest readback proof.
 ---
 
 # Parallels Discord Roundtrip

.agents/skills/security-triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-triage
-description: Triage GitHub security advisories for OpenClaw with high-confidence close/keep decisions, exact tag and commit verification, trust-model checks, optional hardening notes, and a final reply ready to post and copy to clipboard.
+description: Triage OpenClaw security advisories, drafts, and GHSA reports with shipped-tag and trust-model proof.
 ---
 
 # Security Triage

.agents/skills/tag-duplicate-prs-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tag-duplicate-prs-issues
-description: Maintainer workflow for deciding whether an OpenClaw pull request or issue is a duplicate, gathering evidence with ghreplica and pr-search-cli, grouping related work in prtags, and syncing the duplicate grouping back to GitHub through prtags. Use when Codex needs to search for duplicate PRs or issues, create or reuse a duplicate group, enforce one-group-per-target discipline, save duplicate judgments in prtags, or prepare group state for comment sync.
+description: Search duplicate OpenClaw PRs/issues, group related work in prtags, and sync duplicate state to GitHub.
 ---
 
 # Tag Duplicate PRs and Issues

.github/codex/prompts/docs-agent.md

@@ -23,7 +23,7 @@ Allowed paths:
 Required workflow:
 
 1. Run `pnpm docs:list` if available and read relevant docs based on `read_when` hints.
-2. Inspect the triggering event via `$GITHUB_EVENT_PATH`, then review the relevant commit range and changed files.
+2. Inspect the triggering event via `$GITHUB_EVENT_PATH`, then review `$DOCS_AGENT_BASE_SHA..$DOCS_AGENT_HEAD_SHA` and its changed files. If either env var is missing, fall back to the event payload.
 3. Update stale existing documentation, if needed.
 4. Run `pnpm check:docs` if dependencies are available.
 5. Leave the worktree clean if no docs need changes.

.github/codex/prompts/test-performance-agent.md

@@ -18,6 +18,7 @@ Hard limits:
 - Do not update snapshots, generated baselines, inventories, ignore files, lockfiles, package metadata, CI workflows, or release metadata.
 - Do not add dependencies.
 - Do not create, delete, or rename files.
+- Do not do broad refactors or style-only rewrites.
 - Keep changes minimal and focused on the slow or failing tests you can justify from the report.
 - Prefer no edit when a performance improvement is speculative.
 - If `.artifacts/test-perf/baseline-before.json` has `"failed": true`, do not make performance-only edits. First inspect the failed config logs. Edit only when the test failure has an obvious, coverage-preserving fix. If no obvious failure fix exists, leave the worktree clean.
@@ -26,6 +27,7 @@ Good fixes:
 
 - Replace broad partial module mocks, especially `importOriginal()` mocks, with narrow injected dependencies or local runtime seams.
 - Avoid importing heavy barrels in hot tests when a narrow module or helper covers the same behavior.
+- Add or adjust a production lazy/injection seam only when that is the narrowest way to preserve coverage while removing expensive imports or fixing an obvious mock/import failure.
 - Move expensive setup from per-test hooks to shared setup only when state isolation remains correct.
 - Reuse existing fixtures/builders instead of recreating expensive work per case.
 - Mock expensive runtime boundaries directly: filesystem crawls, package registries, provider SDKs, network/process launch, browser/runtime scanners.

.github/labeler.yml

@@ -24,6 +24,11 @@
       - any-glob-to-any-file:
           - "extensions/googlechat/**"
           - "docs/channels/googlechat.md"
+"plugin: google-meet":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/google-meet/**"
+          - "docs/plugins/google-meet.md"
 "channel: imessage":
   - changed-files:
       - any-glob-to-any-file:

.github/workflows/ci.yml

@@ -1344,7 +1344,15 @@ jobs:
       - name: Run changed extension tests
         env:
           OPENCLAW_CHANGED_EXTENSION: ${{ matrix.extension }}
-        run: pnpm test:extension "$OPENCLAW_CHANGED_EXTENSION"
+        run: |
+          set -euo pipefail
+          if [ "$OPENCLAW_CHANGED_EXTENSION" = "telegram" ]; then
+            export OPENCLAW_VITEST_MAX_WORKERS=1
+            export NODE_OPTIONS="${NODE_OPTIONS:+$NODE_OPTIONS }--max-old-space-size=6144"
+            pnpm test:extension "$OPENCLAW_CHANGED_EXTENSION" -- --pool=forks
+            exit 0
+          fi
+          pnpm test:extension "$OPENCLAW_CHANGED_EXTENSION"
 
   # Types, lint, and format check shards.
   check-shard:

.github/workflows/docs-agent.yml

@@ -1,16 +1,15 @@
 name: Docs Agent
 
 on:
-  workflow_run: # zizmor: ignore[dangerous-triggers] main-only docs repair after trusted CI; job gates repository, event, branch, actor, conclusion, and exact current main SHA before using write token
+  workflow_run: # zizmor: ignore[dangerous-triggers] main-only docs repair after trusted CI; job gates repository, event, branch, actor, conclusion, exact current main SHA, and hourly cadence before using write token
     workflows:
       - CI
     types:
       - completed
-  schedule:
-    - cron: "17 5 * * *"
   workflow_dispatch:
 
 permissions:
+  actions: read
   contents: write
 
 concurrency:
@@ -41,17 +40,24 @@ jobs:
           persist-credentials: false
           submodules: false
 
-      - name: Skip superseded workflow runs
-        id: superseded
+      - name: Gate trusted main activity and hourly cadence
+        id: gate
         env:
           EVENT_NAME: ${{ github.event_name }}
+          GH_TOKEN: ${{ github.token }}
           WORKFLOW_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
         run: |
           set -euo pipefail
 
           if [ "$EVENT_NAME" != "workflow_run" ]; then
-            echo "run_agent=true" >> "$GITHUB_OUTPUT"
-            echo "base_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+            head_sha="$(git rev-parse HEAD)"
+            review_base="$(git rev-parse "${head_sha}^" 2>/dev/null || printf '%s' "$head_sha")"
+            {
+              echo "run_agent=true"
+              echo "base_sha=${head_sha}"
+              echo "review_base_sha=${review_base}"
+              echo "review_head_sha=${head_sha}"
+            } >> "$GITHUB_OUTPUT"
             exit 0
           fi
 
@@ -73,17 +79,65 @@ jobs:
             exit 0
           fi
 
-          echo "run_agent=true" >> "$GITHUB_OUTPUT"
-          echo "base_sha=${remote_main}" >> "$GITHUB_OUTPUT"
+          runs_json="$RUNNER_TEMP/docs-agent-runs.json"
+          gh api --method GET "repos/${GITHUB_REPOSITORY}/actions/workflows/docs-agent.yml/runs" \
+            -f branch=main \
+            -f event=workflow_run \
+            -f per_page=100 > "$runs_json"
+
+          one_hour_ago="$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)"
+          recent_runs="$(
+            jq -r \
+              --argjson current_run_id "$GITHUB_RUN_ID" \
+              --arg one_hour_ago "$one_hour_ago" \
+              '.workflow_runs[]
+                | select(.database_id != $current_run_id)
+                | select(.created_at >= $one_hour_ago)
+                | select(.status != "cancelled")
+                | select((.conclusion // "") != "skipped")
+                | [.database_id, .status, (.conclusion // ""), .created_at, .head_sha]
+                | @tsv' "$runs_json"
+          )"
+
+          if [ -n "$recent_runs" ]; then
+            echo "Docs agent already ran or is running within the last hour; skipping."
+            printf '%s\n' "$recent_runs"
+            echo "run_agent=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          review_base="$(
+            jq -r \
+              --argjson current_run_id "$GITHUB_RUN_ID" \
+              --arg remote_main "$remote_main" \
+              '.workflow_runs[]
+                | select(.database_id != $current_run_id)
+                | select(.status != "cancelled")
+                | select((.conclusion // "") != "skipped")
+                | .head_sha
+                | select(. != null and . != "")
+                | select(. != $remote_main)
+              ' "$runs_json" | head -n 1
+          )"
+          if [ -z "$review_base" ] || ! git cat-file -e "${review_base}^{commit}" 2>/dev/null; then
+            review_base="$(git rev-parse "${remote_main}^" 2>/dev/null || printf '%s' "$remote_main")"
+          fi
+
+          {
+            echo "run_agent=true"
+            echo "base_sha=${remote_main}"
+            echo "review_base_sha=${review_base}"
+            echo "review_head_sha=${remote_main}"
+          } >> "$GITHUB_OUTPUT"
 
       - name: Setup Node environment
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         uses: ./.github/actions/setup-node-env
         with:
           install-bun: "false"
 
       - name: Ensure docs agent key exists
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         env:
           OPENAI_API_KEY: ${{ secrets.OPENCLAW_DOCS_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
         run: |
@@ -94,8 +148,11 @@ jobs:
           fi
 
       - name: Run Codex docs agent
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         uses: openai/codex-action@v1
+        env:
+          DOCS_AGENT_BASE_SHA: ${{ steps.gate.outputs.review_base_sha }}
+          DOCS_AGENT_HEAD_SHA: ${{ steps.gate.outputs.review_head_sha }}
         with:
           openai-api-key: ${{ secrets.OPENCLAW_DOCS_AGENT_OPENAI_API_KEY || secrets.OPENAI_API_KEY }}
           prompt-file: .github/codex/prompts/docs-agent.md
@@ -106,7 +163,7 @@ jobs:
           codex-args: '["--full-auto"]'
 
       - name: Enforce existing-docs-only patch
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         run: |
           set -euo pipefail
 
@@ -139,8 +196,8 @@ jobs:
           fi
 
       - name: Restore Node 24 path
-        if: steps.superseded.outputs.run_agent == 'true'
-        run: |
+        if: steps.gate.outputs.run_agent == 'true'
+        run: | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
           set -euo pipefail
           export PATH="${NODE_BIN}:${PATH}"
           echo "${NODE_BIN}" >> "$GITHUB_PATH"
@@ -149,13 +206,13 @@ jobs:
           pnpm -v
 
       - name: Check docs
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         run: pnpm check:docs
 
       - name: Commit docs updates
-        if: steps.superseded.outputs.run_agent == 'true'
+        if: steps.gate.outputs.run_agent == 'true'
         env:
-          BASE_SHA: ${{ steps.superseded.outputs.base_sha }}
+          BASE_SHA: ${{ steps.gate.outputs.base_sha }}
           GITHUB_TOKEN: ${{ github.token }}
           TARGET_BRANCH: main
         run: |

.github/workflows/install-smoke.yml

@@ -5,7 +5,26 @@ on:
     branches: [main]
   pull_request:
     types: [opened, reopened, synchronize, ready_for_review, converted_to_draft]
+  schedule:
+    - cron: "17 3 * * *"
   workflow_dispatch:
+    inputs:
+      run_bun_global_install_smoke:
+        description: Run the Bun global install image-provider smoke
+        required: false
+        default: false
+        type: boolean
+  workflow_call:
+    inputs:
+      ref:
+        description: Git ref to validate
+        required: false
+        type: string
+      run_bun_global_install_smoke:
+        description: Run the Bun global install image-provider smoke
+        required: false
+        default: true
+        type: boolean
 
 permissions:
   contents: read
@@ -24,17 +43,21 @@ jobs:
     outputs:
       docs_only: ${{ steps.manifest.outputs.docs_only }}
       run_install_smoke: ${{ steps.manifest.outputs.run_install_smoke }}
+      run_fast_install_smoke: ${{ steps.manifest.outputs.run_fast_install_smoke }}
+      run_full_install_smoke: ${{ steps.manifest.outputs.run_full_install_smoke }}
+      run_bun_global_install_smoke: ${{ steps.manifest.outputs.run_bun_global_install_smoke }}
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
+          ref: ${{ inputs.ref || github.ref }}
           fetch-depth: 1
           fetch-tags: false
           persist-credentials: false
           submodules: false
 
       - name: Ensure preflight base commit
-        if: github.event_name != 'workflow_dispatch'
+        if: github.event_name != 'workflow_dispatch' && github.event_name != 'schedule' && github.event_name != 'workflow_call'
         uses: ./.github/actions/ensure-base-commit
         with:
           base-sha: ${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}
@@ -46,7 +69,7 @@ jobs:
 
       - name: Detect changed smoke scope
         id: changed_scope
-        if: github.event_name != 'workflow_dispatch' && steps.docs_scope.outputs.docs_only != 'true'
+        if: github.event_name != 'workflow_dispatch' && github.event_name != 'schedule' && github.event_name != 'workflow_call' && steps.docs_scope.outputs.docs_only != 'true'
         shell: bash
         run: |
           set -euo pipefail
@@ -63,26 +86,55 @@ jobs:
         id: manifest
         env:
           OPENCLAW_CI_DOCS_ONLY: ${{ steps.docs_scope.outputs.docs_only }}
-          OPENCLAW_CI_FORCE_INSTALL_SMOKE: ${{ github.event_name == 'workflow_dispatch' && 'true' || 'false' }}
-          OPENCLAW_CI_RUN_CHANGED_SMOKE: ${{ steps.changed_scope.outputs.run_changed_smoke || 'false' }}
+          OPENCLAW_CI_EVENT_NAME: ${{ github.event_name }}
+          OPENCLAW_CI_FORCE_FULL_INSTALL_SMOKE: ${{ (github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || github.event_name == 'workflow_call') && 'true' || 'false' }}
+          OPENCLAW_CI_WORKFLOW_BUN_GLOBAL_INSTALL_SMOKE: ${{ inputs.run_bun_global_install_smoke || 'false' }}
+          OPENCLAW_CI_RUN_FAST_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_fast_install_smoke || steps.changed_scope.outputs.run_changed_smoke || 'false' }}
+          OPENCLAW_CI_RUN_FULL_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_full_install_smoke || 'false' }}
         run: |
           docs_only="${OPENCLAW_CI_DOCS_ONLY:-false}"
-          force_install_smoke="${OPENCLAW_CI_FORCE_INSTALL_SMOKE:-false}"
-          run_changed_smoke="${OPENCLAW_CI_RUN_CHANGED_SMOKE:-false}"
+          event_name="${OPENCLAW_CI_EVENT_NAME:-}"
+          force_full_install_smoke="${OPENCLAW_CI_FORCE_FULL_INSTALL_SMOKE:-false}"
+          workflow_bun_global_install_smoke="${OPENCLAW_CI_WORKFLOW_BUN_GLOBAL_INSTALL_SMOKE:-false}"
+          run_changed_fast_install_smoke="${OPENCLAW_CI_RUN_FAST_INSTALL_SMOKE:-false}"
+          run_changed_full_install_smoke="${OPENCLAW_CI_RUN_FULL_INSTALL_SMOKE:-false}"
+          run_fast_install_smoke=false
+          run_full_install_smoke=false
+          run_bun_global_install_smoke=false
           run_install_smoke=false
-          if [ "$force_install_smoke" = "true" ]; then
+          if [ "$force_full_install_smoke" = "true" ]; then
+            run_fast_install_smoke=true
+            run_full_install_smoke=true
             run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$run_changed_smoke" = "true" ]; then
+          elif [ "$docs_only" != "true" ] && [ "$event_name" != "push" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
+            run_fast_install_smoke=true
+            run_full_install_smoke=true
             run_install_smoke=true
+          elif [ "$docs_only" != "true" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
+            run_fast_install_smoke=true
+            run_install_smoke=true
+          elif [ "$docs_only" != "true" ] && [ "$run_changed_fast_install_smoke" = "true" ]; then
+            run_fast_install_smoke=true
+            run_install_smoke=true
+          fi
+          if [ "$event_name" = "schedule" ]; then
+            run_bun_global_install_smoke=true
+          elif [ "$event_name" = "workflow_dispatch" ] || [ "$event_name" = "workflow_call" ]; then
+            if [ "$workflow_bun_global_install_smoke" = "true" ]; then
+              run_bun_global_install_smoke=true
+            fi
           fi
           {
             echo "docs_only=$docs_only"
             echo "run_install_smoke=$run_install_smoke"
+            echo "run_fast_install_smoke=$run_fast_install_smoke"
+            echo "run_full_install_smoke=$run_full_install_smoke"
+            echo "run_bun_global_install_smoke=$run_bun_global_install_smoke"
           } >> "$GITHUB_OUTPUT"
 
-  install-smoke:
+  install-smoke-fast:
     needs: [preflight]
-    if: needs.preflight.outputs.run_install_smoke == 'true'
+    if: needs.preflight.outputs.run_fast_install_smoke == 'true' && needs.preflight.outputs.run_full_install_smoke != 'true'
     runs-on: blacksmith-16vcpu-ubuntu-2404
     env:
       DOCKER_BUILD_SUMMARY: "false"
@@ -90,6 +142,96 @@ jobs:
     steps:
       - name: Checkout CLI
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Set up Blacksmith Docker Builder
+        uses: useblacksmith/setup-docker-builder@ac083cc84672d01c60d5e8561d0a939b697de542 # v1
+
+      # Blacksmith's builder owns the Docker layer cache; keep smoke builds off
+      # explicit gha cache directives so local tags still load cleanly.
+      - name: Build root Dockerfile smoke image
+        uses: useblacksmith/build-push-action@cbd1f60d194a98cb3be5523b15134501eaf0fbf3 # v2
+        with:
+          context: .
+          file: ./Dockerfile
+          build-args: |
+            OPENCLAW_DOCKER_APT_UPGRADE=0
+            OPENCLAW_EXTENSIONS=matrix
+          tags: |
+            openclaw-dockerfile-smoke:local
+            openclaw-ext-smoke:local
+          load: true
+          push: false
+          provenance: false
+
+      - name: Run root Dockerfile CLI smoke
+        run: |
+          docker run --rm --entrypoint sh openclaw-dockerfile-smoke:local -lc 'which openclaw && openclaw --version'
+
+      - name: Run Docker gateway network e2e
+        env:
+          OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE: openclaw-dockerfile-smoke:local
+          OPENCLAW_GATEWAY_NETWORK_E2E_SKIP_BUILD: "1"
+        run: bash scripts/e2e/gateway-network-docker.sh
+
+      - name: Smoke test Dockerfile with matrix extension build arg
+        run: |
+          docker run --rm --entrypoint sh openclaw-ext-smoke:local -lc '
+            which openclaw &&
+            openclaw --version &&
+            node -e "
+              const Module = require(\"node:module\");
+              const matrixPackage = require(\"/app/extensions/matrix/package.json\");
+              const requireFromMatrix = Module.createRequire(\"/app/extensions/matrix/package.json\");
+              const runtimeDeps = Object.keys(matrixPackage.dependencies ?? {});
+              if (runtimeDeps.length === 0) {
+                throw new Error(
+                  \"matrix package has no declared runtime dependencies; smoke cannot validate install mirroring\",
+                );
+              }
+              for (const dep of runtimeDeps) {
+                requireFromMatrix.resolve(dep);
+              }
+              const { spawnSync } = require(\"node:child_process\");
+              const run = spawnSync(\"openclaw\", [\"plugins\", \"list\", \"--json\"], { encoding: \"utf8\" });
+              if (run.status !== 0) {
+                process.stderr.write(run.stderr || run.stdout || \"plugins list failed\\n\");
+                process.exit(run.status ?? 1);
+              }
+              const parsed = JSON.parse(run.stdout);
+              const matrix = (parsed.plugins || []).find((entry) => entry.id === \"matrix\");
+              if (!matrix) {
+                throw new Error(\"matrix plugin missing from bundled plugin list\");
+              }
+              const matrixDiag = (parsed.diagnostics || []).filter(
+                (diag) =>
+                  typeof diag.source === \"string\" &&
+                  diag.source.includes(\"/extensions/matrix\") &&
+                  typeof diag.message === \"string\" &&
+                  diag.message.includes(\"extension entry escapes package directory\"),
+              );
+              if (matrixDiag.length > 0) {
+                throw new Error(
+                  \"unexpected matrix diagnostics: \" +
+                    matrixDiag.map((diag) => diag.message).join(\"; \"),
+                );
+              }
+            "
+          '
+
+  install-smoke:
+    needs: [preflight]
+    if: needs.preflight.outputs.run_full_install_smoke == 'true'
+    runs-on: blacksmith-16vcpu-ubuntu-2404
+    env:
+      DOCKER_BUILD_SUMMARY: "false"
+      DOCKER_BUILD_RECORD_UPLOAD: "false"
+    steps:
+      - name: Checkout CLI
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
 
       - name: Set up Blacksmith Docker Builder
         uses: useblacksmith/setup-docker-builder@ac083cc84672d01c60d5e8561d0a939b697de542 # v1
@@ -194,13 +336,14 @@ jobs:
           push: false
           provenance: false
 
-      - name: Setup Node environment for local pack smoke
+      - name: Setup Node environment for installer smoke
         uses: ./.github/actions/setup-node-env
         with:
-          install-bun: "true"
+          install-bun: ${{ needs.preflight.outputs.run_bun_global_install_smoke }}
           install-deps: "true"
 
       - name: Run Bun global install image-provider smoke
+        if: needs.preflight.outputs.run_bun_global_install_smoke == 'true'
         env:
           OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE: openclaw-dockerfile-smoke:local
           OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD: "0"
@@ -224,7 +367,7 @@ jobs:
 
   docker-e2e-fast:
     needs: [preflight]
-    if: needs.preflight.outputs.run_install_smoke == 'true'
+    if: needs.preflight.outputs.run_fast_install_smoke == 'true' || needs.preflight.outputs.run_full_install_smoke == 'true'
     runs-on: blacksmith-16vcpu-ubuntu-2404
     timeout-minutes: 8
     env:
@@ -233,6 +376,8 @@ jobs:
     steps:
       - name: Checkout CLI
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.ref }}
 
       - name: Set up Blacksmith Docker Builder
         uses: useblacksmith/setup-docker-builder@ac083cc84672d01c60d5e8561d0a939b697de542 # v1

.github/workflows/openclaw-release-checks.yml

@@ -123,9 +123,18 @@ jobs:
             echo "- Validated SHA: \`${RELEASE_SHA}\`"
             echo "- Cross-OS provider: \`${RELEASE_PROVIDER}\`"
             echo "- Cross-OS mode: \`${RELEASE_MODE}\`"
-            echo "- This run will execute cross-OS release validation, QA Lab parity, Matrix, and Telegram lanes, and the non-Parallels Docker/live/openwebui coverage from the CI migration plan."
+            echo "- This run will execute cross-OS release validation, install smoke, QA Lab parity, Matrix, and Telegram lanes, and the non-Parallels Docker/live/openwebui coverage from the CI migration plan."
           } >> "$GITHUB_STEP_SUMMARY"
 
+  install_smoke_release_checks:
+    needs: [resolve_target]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/install-smoke.yml
+    with:
+      ref: ${{ needs.resolve_target.outputs.ref }}
+      run_bun_global_install_smoke: true
+
   cross_os_release_checks:
     needs: [resolve_target]
     permissions: read-all

.github/workflows/qa-live-transports-convex.yml

@@ -14,6 +14,10 @@ on:
         description: Optional comma-separated Telegram scenario ids
         required: false
         type: string
+      discord_scenario:
+        description: Optional comma-separated Discord scenario ids
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -346,3 +350,95 @@ jobs:
           path: ${{ steps.run_lane.outputs.output_dir }}
           retention-days: 14
           if-no-files-found: warn
+
+  run_live_discord:
+    name: Run Discord live QA lane with Convex leases
+    needs: [authorize_actor, validate_selected_ref]
+    runs-on: blacksmith-32vcpu-ubuntu-2404
+    timeout-minutes: 60
+    environment: qa-live-shared
+    steps:
+      - name: Checkout selected ref
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.validate_selected_ref.outputs.selected_sha }}
+          fetch-depth: 1
+
+      - name: Setup Node environment
+        uses: ./.github/actions/setup-node-env
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          pnpm-version: ${{ env.PNPM_VERSION }}
+          install-bun: "true"
+
+      - name: Validate required QA credential env
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENCLAW_QA_CONVEX_SITE_URL: ${{ secrets.OPENCLAW_QA_CONVEX_SITE_URL }}
+          OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          require_var() {
+            local key="$1"
+            if [[ -z "${!key:-}" ]]; then
+              echo "Missing required ${key}." >&2
+              exit 1
+            fi
+          }
+
+          require_var OPENAI_API_KEY
+          require_var OPENCLAW_QA_CONVEX_SITE_URL
+          require_var OPENCLAW_QA_CONVEX_SECRET_CI
+
+      - name: Build private QA runtime
+        run: pnpm build
+
+      - name: Run Discord live lane
+        id: run_lane
+        shell: bash
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENCLAW_QA_CONVEX_SITE_URL: ${{ secrets.OPENCLAW_QA_CONVEX_SITE_URL }}
+          OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
+          OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
+          OPENCLAW_QA_DISCORD_CAPTURE_CONTENT: "1"
+          INPUT_SCENARIO: ${{ github.event_name == 'workflow_dispatch' && inputs.discord_scenario || '' }}
+        run: |
+          set -euo pipefail
+
+          output_dir=".artifacts/qa-e2e/discord-live-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          scenario_args=()
+
+          if [[ -n "${INPUT_SCENARIO// }" ]]; then
+            IFS=',' read -r -a raw_scenarios <<<"${INPUT_SCENARIO}"
+            for raw in "${raw_scenarios[@]}"; do
+              scenario="$(printf '%s' "${raw}" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+              if [[ -n "${scenario}" ]]; then
+                scenario_args+=(--scenario "${scenario}")
+              fi
+            done
+          fi
+
+          echo "output_dir=${output_dir}" >> "$GITHUB_OUTPUT"
+
+          pnpm openclaw qa discord \
+            --repo-root . \
+            --output-dir "${output_dir}" \
+            --provider-mode live-frontier \
+            --model openai/gpt-5.4 \
+            --alt-model openai/gpt-5.4 \
+            --fast \
+            --credential-source convex \
+            --credential-role ci \
+            "${scenario_args[@]}"
+
+      - name: Upload Discord QA artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: qa-live-discord-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ steps.run_lane.outputs.output_dir }}
+          retention-days: 14
+          if-no-files-found: warn

.github/workflows/test-performance-agent.yml

@@ -181,7 +181,7 @@ jobs:
 
       - name: Restore Node 24 path
         if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
-        run: |
+        run: | # zizmor: ignore[github-env] NODE_BIN is set by the trusted local setup-node-env action in this same job
           set -euo pipefail
           export PATH="${NODE_BIN}:${PATH}"
           echo "${NODE_BIN}" >> "$GITHUB_PATH"
@@ -227,7 +227,6 @@ jobs:
       - name: Commit test performance updates
         if: steps.gate.outputs.run_agent == 'true' && steps.patch.outputs.has_changes == 'true'
         env:
-          BASE_SHA: ${{ steps.gate.outputs.base_sha }}
           GITHUB_TOKEN: ${{ github.token }}
           TARGET_BRANCH: main
         run: |
@@ -253,9 +252,14 @@ jobs:
               exit 0
             fi
             remote_main="$(git rev-parse "origin/${TARGET_BRANCH}")"
-            if [ "$remote_main" != "$BASE_SHA" ]; then
-              echo "main advanced from ${BASE_SHA} to ${remote_main}; skipping stale test performance update."
-              exit 0
+            if [ "$remote_main" != "$(git rev-parse HEAD^)" ]; then
+              echo "main advanced; rebasing test performance update onto ${remote_main}."
+              if ! git rebase "origin/${TARGET_BRANCH}"; then
+                echo "Test performance update no longer applies cleanly; skipping stale update."
+                git rebase --abort || true
+                exit 0
+              fi
+              pnpm check:changed
             fi
             echo "Test performance update attempt ${attempt} failed; retrying."
             sleep $((attempt * 2))

AGENTS.md

@@ -61,7 +61,7 @@ Scoped guides:
 - Build: `pnpm build`
 - Smart local gate: `pnpm check:changed` (scoped typecheck/lint/guards + relevant tests)
 - Explain smart gate: `pnpm changed:lanes --json`
-- Pre-commit view: `pnpm check:changed --staged`
+- Staged gate preview: `pnpm check:changed --staged`
 - Normal full prod sweep: `pnpm check` (prod typecheck/lint/guards, no tests)
 - Full tests: `pnpm test`
 - Changed tests only: `pnpm test:changed`
@@ -95,11 +95,13 @@ Scoped guides:
 - Before closing an issue/PR: add a comment explaining why, usually duplicate/invalid, with the canonical issue/PR when relevant.
 - PR links: `gh pr list --state open --search '<issue-or-terms>' --json number,title,updatedAt,headRefName --limit 20`; use `gh pr view <n> --json number,title,body,closingIssuesReferences,files,statusCheckRollup,reviewDecision` only after shortlist.
 - CI polling: keep full `gh` capability, but request only needed fields. Known run status: `gh api repos/<owner>/<repo>/actions/runs/<id> --jq '{status,conclusion,head_sha,updated_at,name,path}'`.
+- Non-blocking background workflows: `Auto response`, `Docs Sync Publish Repo`, `Docs Agent`, and `Test Performance Agent` are service/agent work. Do not wait on, rerun, or fix them during normal push/PR verification unless the user explicitly asks or the task is about those workflows. Report them as background if mentioned.
+- `/landpr` CI wait scope: do not idle on pending `auto-response`/`Auto response` or `check-docs`. Treat docs as local proof unless `check-docs` already failed with a relevant, actionable error. If required product/code gates and touched-surface local gates are green, proceed without waiting for docs-only or auto-response automation.
 - Waiting: poll lightly, usually 30-60s backoff. Fetch jobs/logs/artifacts only after completion/failure or when job detail is needed; avoid repeated workflow + run + jobs loops.
 
 ## Gates
 
-- Pre-commit hook: staged format/lint, then `pnpm check:changed --staged`; docs/markdown-only skips changed-scope check; `FAST_COMMIT=1` / `scripts/committer --fast` skips changed-scope check only.
+- Pre-commit hook: staged formatting only. It does not run lint, typecheck, or tests.
 - Changed lanes:
   - core prod => core prod typecheck + core tests
   - core tests => core test typecheck/tests only
@@ -107,11 +109,11 @@ Scoped guides:
   - extension tests => extension test typecheck/tests only
   - public SDK/plugin contract => extension prod/test validation too
   - unknown root/config => all lanes
-- Local loop: prefer `pnpm check:changed`; use `pnpm test:changed` for tests only; use `pnpm check` for full prod TS/lint sweep without tests.
+- Local loop: run `pnpm check:changed` explicitly before handoff/push; use `pnpm test:changed` for tests only; use `pnpm check` for full prod TS/lint sweep without tests.
 - Landing on `main`: verify touched surface near landing; default bar is `pnpm check` + `pnpm test` when feasible.
 - Hard build gate: run/pass `pnpm build` before push if build output, packaging, lazy/module boundaries, or published surfaces can change.
 - Do not land related failing format/lint/type/build/tests. If failures are unrelated on latest `origin/main`, say so and give scoped proof.
-- Fast commit escape hatch: use `scripts/committer --fast "<msg>" <file...>` only after the exact staged change set was already validated with equal-or-stronger gates, or after rerunning an isolated flaky failure with proof. State the gates/proof in handoff.
+- Commit helper is formatting-only; validation gates are explicit commands, not commit side effects.
 - CI architecture gate: `check-additional`; local equivalent `pnpm check:architecture`.
 - Config docs drift: `pnpm config:docs:gen/check`
 - Plugin SDK API drift: `pnpm plugin-sdk:api:gen/check`
@@ -162,7 +164,7 @@ Scoped guides:
 
 ## Git
 
-- Use `scripts/committer "<msg>" <file...>`; stage only intended files. Use `--fast` only under the Gates escape-hatch rule above.
+- Use `scripts/committer "<msg>" <file...>`; stage only intended files. It formats staged files only; run validation separately.
 - Commits: conventional-ish, concise/action-oriented. Group related changes.
 - No manual stash/autostash unless explicitly requested. No branch/worktree changes unless requested.
 - No merge commits on `main`; rebase on latest `origin/main` before push.

CHANGELOG.md

@@ -6,25 +6,53 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Control UI/chat: add a Steer action on queued messages so a browser follow-up can be injected into the active run without retyping it.
+- Control UI/Talk: add browser WebRTC realtime voice sessions backed by OpenAI Realtime, with Gateway-minted ephemeral client secrets and `openclaw_agent_consult` handoff to the full OpenClaw agent.
+- Agents/tools: add optional per-call `timeoutMs` support for image, video, music, and TTS generation tools so agents can extend provider request timeouts only when a specific generation needs it.
 - Agents/subagents: add optional forked context for native `sessions_spawn` runs so agents can let a child inherit the requester transcript when needed, while keeping clean isolated sessions as the default; includes prompt guidance, context-engine hook metadata, docs, and QA coverage.
 - Codex harness: add structured debug logging for embedded harness selection decisions so `/status` stays simple while gateway logs explain auto-selection and Pi fallback reasons. (#70760) Thanks @100yenadmin.
-- Providers/OpenAI: add forward-compatible `gpt-5.5` and `gpt-5.5-pro` support for OpenAI API keys, OpenAI Codex OAuth, and the Codex CLI default model.
+- Dependencies/Pi: update bundled Pi packages to `0.70.0`, use Pi's upstream `gpt-5.5` catalog metadata for OpenAI and OpenAI Codex, and keep only local `gpt-5.5-pro` forward-compat handling.
+- Models/CLI: avoid broad registry enumeration for default `openclaw models list`, reducing default listing latency while preserving configured-row output. (#70883) Thanks @shakkernerd.
+- Models/CLI: split `openclaw models list` row-source orchestration and registry loading into narrower helpers without changing list output behavior. (#70867) Thanks @shakkernerd.
+- Plugins/Google Meet: add a bundled participant plugin with personal Google auth, explicit meeting URL joins, Chrome and Twilio transports, and realtime voice support. (#70765) Thanks @steipete.
+- Plugins/Google Meet: default Chrome realtime sessions to OpenAI plus SoX `rec`/`play` audio bridge commands, so the usual setup only needs the plugin enabled and `OPENAI_API_KEY`.
 - Providers/OpenAI: add image generation and reference-image editing through Codex OAuth, so `openai/gpt-image-2` works without an `OPENAI_API_KEY`. Fixes #70703.
+- Providers/OpenRouter: add image generation and reference-image editing through `image_generate`, so OpenRouter image models work with `OPENROUTER_API_KEY`. Fixes #55066 via #67668. Thanks @notamicrodose.
+- Image generation: let agents request provider-supported quality and output format hints, and pass OpenAI-specific background, moderation, compression, and user hints through the `image_generate` tool. (#70503) Thanks @ottodeng.
+- Plugins/Google Meet: let realtime Meet sessions consult the full OpenClaw agent for deeper answers while staying in the live voice loop.
 
 ### Fixes
 
-- Agents/OpenAI: surface selected-model capacity failures with a model-switch hint instead of the generic empty-response error. Thanks @vincentkoc.
+- Agents/replay: stop OpenAI/Codex transcript replay from synthesizing missing tool results while still preserving synthetic repair on Anthropic, Gemini, and Bedrock transport-owned sessions. (#61556) Thanks @VictorJeon and @vincentkoc.
+- Telegram/media replies: parse remote markdown image syntax into outbound media payloads on the final reply path, so Telegram group chats stop falling back to plain-text image URLs when the model or a tool emits `![...](...)` instead of a `MEDIA:` token. (#66191) Thanks @apezam and @vincentkoc.
+- Agents/WebChat: surface non-retryable provider failures such as billing, auth, and rate-limit errors from the embedded runner instead of logging `surface_error` and leaving webchat with no rendered error. Fixes #70124. (#70848) Thanks @truffle-dev.
+- Memory/CLI: declare the built-in `local` embedding provider in the memory-core manifest, so standalone `openclaw memory status`, `index`, and `search` can resolve local embeddings just like the gateway runtime. Fixes #70836. (#70873) Thanks @mattznojassist.
+- Gateway/WebChat: preserve image attachments for text-only primary models by offloading them as media refs instead of dropping them, so configured image tools can still inspect the original file. Fixes #68513, #44276, #51656, #70212.
+- Plugins/Google Meet: hang up delegated Twilio calls on leave, clean up Chrome realtime audio bridges when launch fails, and use a flat provider-safe tool schema.
+- Media understanding: honor explicit image-model configuration before native-vision skips, including `agents.defaults.imageModel`, `tools.media.image.models`, and provider image defaults such as MiniMax VL when the active chat model is text-only. Fixes #47614, #63722, #69171.
+- Codex/media understanding: support `codex/*` image models through bounded Codex app-server image turns, while keeping `openai-codex/*` on the OpenAI Codex OAuth route and validating app-server responses against generated protocol contracts. Fixes #70201.
+- Providers/OpenAI Codex: synthesize the `openai-codex/gpt-5.5` OAuth model row when Codex catalog discovery omits it, so cron and subagent runs do not fail with `Unknown model` while the account is authenticated.
+- Models/CLI: keep `openclaw models list` read-only while still showing eligible configured-provider rows, so listing models no longer rewrites per-agent `models.json`. (#70847) Thanks @shakkernerd.
+- Providers/Google: honor the private-network SSRF opt-in for Gemini image generation requests, so trusted proxy setups that resolve Google API hosts to private addresses can use `image_generate`. Fixes #67216.
+- Agents/transport: stop embedded runs from lowering the process-wide undici stream timeouts, so slow Gemini image generation and other long-running provider requests no longer inherit short run-attempt headers timeouts. Fixes #70423. Thanks @giangthb.
+- Providers/OpenRouter: send image-understanding prompts as user text before image parts, restoring non-empty vision responses for OpenRouter multimodal models. Fixes #70410.
+- Plugins/providers: mirror runtime auth choices in bundled provider manifests and detect `KIMI_API_KEY` for Moonshot/Kimi web search before plugin runtime loads. Thanks @vincentkoc.
+- Memory/QMD: recreate stale managed QMD collections when startup repair finds the collection name already exists, so root memory narrows back to `MEMORY.md` instead of staying on broad workspace markdown indexing.
+- Agents/OpenAI: surface selected-model capacity failures from PI, Codex, and auto-reply harness paths with a model-switch hint instead of the generic empty-response error. Thanks @vincentkoc.
+- Providers/OpenAI: route `openai/gpt-image-2` through configured Codex OAuth directly when an `openai-codex` profile is active, instead of probing `OPENAI_API_KEY` first.
+- Providers/OpenAI: harden image generation auth routing and Codex OAuth response parsing so fallback only applies to public OpenAI API routes and bounded SSE results. Thanks @Takhoffman.
+- Providers/OpenAI: honor the private-network SSRF opt-in for OpenAI-compatible image generation endpoints, so trusted LocalAI/LAN `image_generate` routes work without disabling SSRF checks globally. Fixes #62879. Thanks @seitzbg.
 - Providers/OpenAI: stop advertising the removed `gpt-5.3-codex-spark` Codex model through fallback catalogs, and suppress stale rows with a GPT-5.5 recovery hint.
 - Plugins/QR: replace legacy `qrcode-terminal` QR rendering with bounded `qrcode-tui` helpers for plugin login/setup flows. (#65969) Thanks @vincentkoc.
-- ACPX/Codex: stop the embedded Codex ACP auth bridge from falling back to raw `~/.codex` file copies; ACPX now only uses OpenClaw's canonical Codex OAuth bridge.
 - Voice-call/realtime: wait for OpenAI session configuration before greeting or forwarding buffered audio, and reject non-allowlisted Twilio callers before stream setup. (#43501) Thanks @forrestblount.
+- ACPX/Codex: stop materializing `auth.json` bridge files for Codex ACP, Codex app-server, and Codex CLI runs; Codex-owned runtimes now use their normal `CODEX_HOME`/`~/.codex` auth path directly.
 - Auto-reply/system events: route async exec-event completion replies through the persisted session delivery context, so long-running command results return to the originating channel instead of being dropped when live origin metadata is missing. (#70258) Thanks @wzfukui.
 - OpenAI/image generation: send reference-image edits as guarded multipart uploads instead of JSON data URLs, restoring complex multi-reference `gpt-image-2` edits. Fixes #70642. Thanks @dashhuang.
 - QA channel/security: reject non-HTTP(S) inbound attachment URLs before media fetch, and log rejected schemes so suspicious or misconfigured payloads are visible during debugging. (#70708) Thanks @vincentkoc.
 - Plugins/install: link the host OpenClaw package into external plugins that declare `openclaw` as a peer dependency, so peer-only plugin SDK imports resolve after install without bundling a duplicate host package. (#70462) Thanks @anishesg.
 - Teams/security: require shared Bot Framework audience tokens to name the configured Teams app via verified `appid` or `azp`, blocking cross-bot token replay on the global audience. (#70724) Thanks @vincentkoc.
 - Plugins/startup: resolve bundled plugin Jiti loads relative to the target plugin module instead of the central loader, so Bun global installs no longer hang while discovering bundled image providers. (#70073) Thanks @yidianyiko.
-- Anthropic/CLI security: stop Claude CLI backend defaults from forcing `bypassPermissions`, and strip malformed permission-mode overrides instead of silently falling back to a bypass. (#70723) Thanks @vincentkoc.
+- Anthropic/CLI security: derive Claude CLI `bypassPermissions` from OpenClaw's existing YOLO exec policy, preserve explicit raw Claude `--permission-mode` overrides, and strip malformed permission-mode args instead of silently falling back to a bypass. (#70723) Thanks @vincentkoc.
 - Android/security: require loopback-only cleartext gateway connections on Android manual and scanned routes, so private-LAN and link-local `ws://` endpoints now fail closed unless TLS is enabled. (#70722) Thanks @vincentkoc.
 - Pairing/security: require private-IP or loopback hosts for cleartext mobile pairing, and stop treating `.local` or dotless hostnames as safe cleartext endpoints. (#70721) Thanks @vincentkoc.
 - Plugins/security: stop setup-api lookup from falling back to the launch directory, so workspace-local `extensions/<plugin>/setup-api.*` files cannot be executed during provider setup resolution. (#70718) Thanks @drobison00.
@@ -42,12 +70,14 @@ Docs: https://docs.openclaw.ai
 - WhatsApp/security: keep contact/vCard/location structured-object free text out of the inline message body and render it through fenced untrusted metadata JSON, limiting hidden prompt-injection payloads in names, phone fields, and location labels/comments.
 - Group-chat/security: keep channel-sourced group names and participant labels out of inline group system prompts and render them through fenced untrusted metadata JSON.
 - Agents/replay: preserve Kimi-style `functions.<name>:<index>` tool-call IDs during strict replay sanitization so custom OpenAI-compatible Kimi routes keep multi-turn tool use intact. (#70693) Thanks @geri4.
-- Plugins/startup: restore bundled plugin `openclaw/plugin-sdk/*` resolution from packaged installs and external runtime-deps stage roots, so Telegram/Discord no longer crash-loop with `Cannot find package 'openclaw'` after missing dependency repair.
+- Plugins/startup: restore bundled plugin `openclaw/plugin-sdk/*` resolution from packaged installs and external runtime-deps stage roots, so Telegram/Discord no longer crash-loop with `Cannot find package 'openclaw'` after missing dependency repair. (#70852) Thanks @simonemacario.
 - CLI/Claude: run the same prompt-build hooks and trigger/channel context on `claude-cli` turns as on direct embedded runs, keeping Claude Code sessions aligned with OpenClaw workspace identity, routing, and hook-driven prompt mutations. (#70625) Thanks @mbelinky.
 - Discord/plugin startup: keep subagent hooks lazy behind Discord's channel entry so packaged entry imports stay narrow and report import failures with the channel id and entry path.
 - Memory/doctor: keep root durable memory canonicalized on `MEMORY.md`, stop treating lowercase `memory.md` as a runtime fallback, and let `openclaw doctor --fix` merge true split-brain root files into `MEMORY.md` with a backup. (#70621) Thanks @mbelinky.
 - Providers/Anthropic Vertex: restore ADC-backed model discovery after the lightweight provider-discovery path by resolving emitted discovery entries, exposing synthetic auth on bootstrap discovery, and honoring copied env snapshots when probing the default GCP ADC path. Fixes #65715. (#65716) Thanks @feiskyer.
 - Codex harness/status: pin embedded harness selection per session, show active non-PI harness ids such as `codex` in `/status`, and keep legacy transcripts on PI until `/new` or `/reset` so config changes cannot hot-switch existing sessions.
+- Gateway/security: fail closed on agent-driven `gateway config.apply`/`config.patch` runtime edits by allowlisting a narrow set of agent-tunable prompt, model, and mention-gating paths (including Telegram topic-level `requireMention`) instead of relying on a hand-maintained denylist of protected subtrees that could miss new sensitive config keys. (#70726) Thanks @drobison00.
+- Webhooks/security: re-resolve `SecretRef`-backed webhook route secrets on each request so `openclaw secrets reload` revokes the previous secret immediately instead of waiting for a gateway restart. (#70727) Thanks @drobison00.
 
 ## 2026.4.22
 

apps/android/app/build.gradle.kts

@@ -65,8 +65,8 @@ android {
         applicationId = "ai.openclaw.app"
         minSdk = 31
         targetSdk = 36
-        versionCode = 2026042300
-        versionName = "2026.4.23"
+        versionCode = 2026042400
+        versionName = "2026.4.24"
         ndk {
             // Support all major ABIs — native libs are tiny (~47 KB per ABI)
             abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")

apps/ios/CHANGELOG.md

@@ -1,5 +1,9 @@
 # OpenClaw iOS Changelog
 
+## 2026.4.24 - 2026-04-24
+
+Maintenance update for the current OpenClaw development release.
+
 ## 2026.4.23 - 2026-04-23
 
 Maintenance update for the current OpenClaw development release.

apps/ios/Config/Version.xcconfig

@@ -2,8 +2,8 @@
 // Source of truth: apps/ios/version.json
 // Generated by scripts/ios-sync-versioning.ts.
 
-OPENCLAW_IOS_VERSION = 2026.4.23
-OPENCLAW_MARKETING_VERSION = 2026.4.23
+OPENCLAW_IOS_VERSION = 2026.4.24
+OPENCLAW_MARKETING_VERSION = 2026.4.24
 OPENCLAW_BUILD_VERSION = 1
 
 #include? "../build/Version.xcconfig"

apps/ios/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "2026.4.23"
+  "version": "2026.4.24"
 }

apps/macos/Sources/OpenClaw/Resources/Info.plist

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.4.23</string>
+    <string>2026.4.24</string>
     <key>CFBundleVersion</key>
-    <string>2026042300</string>
+    <string>2026042400</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2325,6 +2325,66 @@ public struct TalkConfigResult: Codable, Sendable {
     }
 }
 
+public struct TalkRealtimeSessionParams: Codable, Sendable {
+    public let sessionkey: String?
+    public let provider: String?
+    public let model: String?
+    public let voice: String?
+    public let instructions: String?
+
+    public init(
+        sessionkey: String?,
+        provider: String?,
+        model: String?,
+        voice: String?,
+        instructions: String?)
+    {
+        self.sessionkey = sessionkey
+        self.provider = provider
+        self.model = model
+        self.voice = voice
+        self.instructions = instructions
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case provider
+        case model
+        case voice
+        case instructions
+    }
+}
+
+public struct TalkRealtimeSessionResult: Codable, Sendable {
+    public let provider: String
+    public let clientsecret: String
+    public let model: String?
+    public let voice: String?
+    public let expiresat: Double?
+
+    public init(
+        provider: String,
+        clientsecret: String,
+        model: String?,
+        voice: String?,
+        expiresat: Double?)
+    {
+        self.provider = provider
+        self.clientsecret = clientsecret
+        self.model = model
+        self.voice = voice
+        self.expiresat = expiresat
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case provider
+        case clientsecret = "clientSecret"
+        case model
+        case voice
+        case expiresat = "expiresAt"
+    }
+}
+
 public struct TalkSpeakParams: Codable, Sendable {
     public let text: String
     public let voiceid: String?

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

@@ -2325,6 +2325,66 @@ public struct TalkConfigResult: Codable, Sendable {
     }
 }
 
+public struct TalkRealtimeSessionParams: Codable, Sendable {
+    public let sessionkey: String?
+    public let provider: String?
+    public let model: String?
+    public let voice: String?
+    public let instructions: String?
+
+    public init(
+        sessionkey: String?,
+        provider: String?,
+        model: String?,
+        voice: String?,
+        instructions: String?)
+    {
+        self.sessionkey = sessionkey
+        self.provider = provider
+        self.model = model
+        self.voice = voice
+        self.instructions = instructions
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case provider
+        case model
+        case voice
+        case instructions
+    }
+}
+
+public struct TalkRealtimeSessionResult: Codable, Sendable {
+    public let provider: String
+    public let clientsecret: String
+    public let model: String?
+    public let voice: String?
+    public let expiresat: Double?
+
+    public init(
+        provider: String,
+        clientsecret: String,
+        model: String?,
+        voice: String?,
+        expiresat: Double?)
+    {
+        self.provider = provider
+        self.clientsecret = clientsecret
+        self.model = model
+        self.voice = voice
+        self.expiresat = expiresat
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case provider
+        case clientsecret = "clientSecret"
+        case model
+        case voice
+        case expiresat = "expiresAt"
+    }
+}
+
 public struct TalkSpeakParams: Codable, Sendable {
     public let text: String
     public let voiceid: String?

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-6b142e6a8aa513ccd8f9cfbf7e95fa4919fb6fca7aeaa841f57ad9e39e8901a9  config-baseline.json
-a4e167f169db58d71c385a31fa2b980772f9fee963e70dd9553f63536cae5aed  config-baseline.core.json
+d3b5638e205a94e40d07aa1830c8d57135df18ff9388fb7d72ee84c791ac293f  config-baseline.json
+bf00f7910d8f0d8e12592e8a1c6bd0397f8e62fef2c11eb0cbd3b3a3e2a78ffe  config-baseline.core.json
 22d7cd6d8279146b2d79c9531a55b80b52a2c99c81338c508104729154fdd02d  config-baseline.channel.json
 a91304e3566ecc8906f199b88a2e38eaee86130aad799bf4d62921e2f0ddc1b5  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-bc55649a80027756f37892424598653a81fec4bff7b074358fe34d08c7696ebc  plugin-sdk-api-baseline.json
-312a29d50b4959e4a8e242bb7559548d895a2e03d5ed1b5a395b1133de090578  plugin-sdk-api-baseline.jsonl
+96905c33f4498446f612ae17dee6affdf84ef0e2e5a0f25bf7191c315f5b826f  plugin-sdk-api-baseline.json
+d8eb6331562fde29531eaac18409bb7fabcc70623bf25395f8e5710a49765f0f  plugin-sdk-api-baseline.jsonl

docs/.i18n/glossary.zh-CN.json

@@ -323,6 +323,10 @@
     "source": "env var",
     "target": "环境变量"
   },
+  {
+    "source": "Google Meet Plugin",
+    "target": "Google Meet 插件"
+  },
   {
     "source": "Plugin SDK",
     "target": "插件 SDK"

docs/automation/auth-monitoring.md

@@ -4,3 +4,8 @@ title: "Auth monitoring"
 ---
 
 This page moved to [Authentication](/gateway/authentication). See [Authentication](/gateway/authentication) for auth monitoring documentation.
+
+## Related
+
+- [Automation troubleshooting](/automation/troubleshooting)
+- [Hooks](/automation/hooks)

docs/automation/clawflow.md

@@ -4,3 +4,9 @@ title: "ClawFlow"
 ---
 
 ClawFlow was renamed to [Task Flow](/automation/taskflow). See [Task Flow](/automation/taskflow) for the current documentation.
+
+## Related
+
+- [Task flow](/automation/taskflow)
+- [Standing orders](/automation/standing-orders)
+- [Hooks](/automation/hooks)

docs/automation/cron-jobs.md

@@ -235,7 +235,7 @@ Run an isolated agent turn:
 curl -X POST http://127.0.0.1:18789/hooks/agent \
   -H 'Authorization: Bearer SECRET' \
   -H 'Content-Type: application/json' \
-  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.5"}'
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
 ```
 
 Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.

docs/automation/cron-vs-heartbeat.md

@@ -4,3 +4,8 @@ title: "Cron vs heartbeat"
 ---
 
 This page moved to [Automation & Tasks](/automation). See [Automation & Tasks](/automation) for the decision guide comparing cron and heartbeat.
+
+## Related
+
+- [Scheduled tasks](/automation/cron-jobs)
+- [Background tasks](/automation/tasks)

docs/automation/gmail-pubsub.md

@@ -4,3 +4,8 @@ title: "Gmail PubSub"
 ---
 
 This page moved to [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration). See [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration) for Gmail PubSub documentation.
+
+## Related
+
+- [Webhook](/automation/webhook)
+- [Automation troubleshooting](/automation/troubleshooting)

docs/automation/hooks.md

@@ -207,7 +207,7 @@ Runs `BOOT.md` from the active workspace when the gateway starts.
 
 Plugins can register hooks through the Plugin SDK for deeper integration: intercepting tool calls, modifying prompts, controlling message flow, and more. The Plugin SDK exposes 28 hooks covering model resolution, agent lifecycle, message flow, tool execution, subagent coordination, and gateway lifecycle.
 
-For the complete plugin hook reference including `before_tool_call`, `before_agent_reply`, `before_install`, and all other plugin hooks, see [Plugin Architecture](/plugins/architecture#provider-runtime-hooks).
+For the complete plugin hook reference including `before_tool_call`, `before_agent_reply`, `before_install`, and all other plugin hooks, see [Plugin Architecture](/plugins/architecture-internals#provider-runtime-hooks).
 
 ## Configuration
 
@@ -315,5 +315,5 @@ Check for missing binaries (PATH), environment variables, config values, or OS c
 
 - [CLI Reference: hooks](/cli/hooks)
 - [Webhooks](/automation/cron-jobs#webhooks)
-- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — full plugin hook reference
+- [Plugin Architecture](/plugins/architecture-internals#provider-runtime-hooks) — full plugin hook reference
 - [Configuration](/gateway/configuration-reference#hooks)

docs/automation/poll.md

@@ -4,3 +4,9 @@ title: "Polls"
 ---
 
 This page moved to [Message tool](/cli/message). See [Message tool](/cli/message) for poll documentation.
+
+## Related
+
+- [Webhook](/automation/webhook)
+- [Scheduled tasks](/automation/cron-jobs)
+- [Background tasks](/automation/tasks)

docs/automation/troubleshooting.md

@@ -4,3 +4,9 @@ title: "Automation troubleshooting"
 ---
 
 This page moved to [Scheduled Tasks](/automation/cron-jobs#troubleshooting). See [Scheduled Tasks](/automation/cron-jobs#troubleshooting) for troubleshooting documentation.
+
+## Related
+
+- [Hooks](/automation/hooks)
+- [Background tasks](/automation/tasks)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/automation/webhook.md

@@ -4,3 +4,9 @@ title: "Webhooks"
 ---
 
 This page moved to [Scheduled Tasks](/automation/cron-jobs#webhooks). See [Scheduled Tasks](/automation/cron-jobs#webhooks) for webhook documentation.
+
+## Related
+
+- [Poll](/automation/poll)
+- [Gmail PubSub](/automation/gmail-pubsub)
+- [Hooks](/automation/hooks)

docs/channels/broadcast-groups.md

@@ -438,3 +438,9 @@ Planned features:
 - [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools)
 - [Routing Configuration](/channels/channel-routing)
 - [Session Management](/concepts/session)
+
+## Related
+
+- [Groups](/channels/groups)
+- [Channel routing](/channels/channel-routing)
+- [Pairing](/channels/pairing)

docs/channels/channel-routing.md

@@ -141,3 +141,9 @@ Inbound replies include:
 - Quoted context is appended to `Body` as a `[Replying to ...]` block.
 
 This is consistent across channels.
+
+## Related
+
+- [Groups](/channels/groups)
+- [Broadcast groups](/channels/broadcast-groups)
+- [Pairing](/channels/pairing)

docs/channels/discord.md

@@ -1134,7 +1134,7 @@ openclaw logs --follow
 
 ## Configuration reference
 
-Primary reference: [Configuration reference - Discord](/gateway/configuration-reference#discord).
+Primary reference: [Configuration reference - Discord](/gateway/config-channels#discord).
 
 <Accordion title="High-signal Discord fields">
 

docs/channels/feishu.md

@@ -16,7 +16,7 @@ Feishu/Lark is an all-in-one collaboration platform where teams chat, share docu
 
 ## Quick start
 
-> **Requires OpenClaw 2026.4.23 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
+> **Requires OpenClaw 2026.4.24 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
 
 <Steps>
   <Step title="Run the channel setup wizard">

docs/channels/group-messages.md

@@ -82,3 +82,9 @@ Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.
 - Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
 - Session store entries will appear as `agent:<agentId>:whatsapp:group:<jid>` in the session store (`~/.openclaw/agents/<agentId>/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
 - Typing indicators in groups follow `agents.defaults.typingMode` (default: `message` when unmentioned).
+
+## Related
+
+- [Groups](/channels/groups)
+- [Channel routing](/channels/channel-routing)
+- [Broadcast groups](/channels/broadcast-groups)

docs/channels/groups.md

@@ -138,7 +138,7 @@ Want “groups can only see folder X” instead of “no host access”? Keep `w
 
 Related:
 
-- Configuration keys and defaults: [Gateway configuration](/gateway/configuration-reference#agentsdefaultssandbox)
+- Configuration keys and defaults: [Gateway configuration](/gateway/config-agents#agentsdefaultssandbox)
 - Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
 - Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
 
@@ -413,3 +413,10 @@ See [WhatsApp](/channels/whatsapp#system-prompts) for the canonical WhatsApp sys
 ## WhatsApp specifics
 
 See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+
+## Related
+
+- [Group messages](/channels/group-messages)
+- [Broadcast groups](/channels/broadcast-groups)
+- [Channel routing](/channels/channel-routing)
+- [Pairing](/channels/pairing)

docs/channels/imessage.md

@@ -23,7 +23,7 @@ Status: legacy external CLI integration. Gateway spawns `imsg rpc` and communica
   <Card title="Pairing" icon="link" href="/channels/pairing">
     iMessage DMs default to pairing mode.
   </Card>
-  <Card title="Configuration reference" icon="settings" href="/gateway/configuration-reference#imessage">
+  <Card title="Configuration reference" icon="settings" href="/gateway/config-channels#imessage">
     Full iMessage field reference.
   </Card>
 </CardGroup>
@@ -413,7 +413,7 @@ imsg send <handle> "test"
 
 ## Configuration reference pointers
 
-- [Configuration reference - iMessage](/gateway/configuration-reference#imessage)
+- [Configuration reference - iMessage](/gateway/config-channels#imessage)
 - [Gateway configuration](/gateway/configuration)
 - [Pairing](/channels/pairing)
 - [BlueBubbles](/channels/bluebubbles)

docs/channels/location.md

@@ -63,3 +63,9 @@ The prompt renderer treats `LocationName`, `LocationAddress`, and `LocationCapti
 - **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
 - **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` populate `LocationCaption`.
 - **Matrix**: `geo_uri` is parsed as a pin location; altitude is ignored and `LocationIsLive` is always false.
+
+## Related
+
+- [Location command (nodes)](/nodes/location-command)
+- [Camera capture](/nodes/camera)
+- [Media understanding](/nodes/media-understanding)

docs/channels/matrix.md

@@ -670,7 +670,7 @@ If multiple Matrix accounts are configured and one account id is `default`, Open
 If you configure multiple named accounts, set `defaultAccount` or pass `--account <id>` for CLI commands that rely on implicit account selection.
 Pass `--account <id>` to `openclaw matrix verify ...` and `openclaw matrix devices ...` when you want to override that implicit selection for one command.
 
-See [Configuration reference](/gateway/configuration-reference#multi-account-all-channels) for the shared multi-account pattern.
+See [Configuration reference](/gateway/config-channels#multi-account-all-channels) for the shared multi-account pattern.
 
 ## Private/LAN homeservers
 

docs/channels/qa-channel.md

@@ -104,3 +104,9 @@ Follow-up work will add:
 - provider/model matrix execution
 - richer scenario discovery
 - OpenClaw-native orchestration later
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Groups](/channels/groups)
+- [Channels overview](/channels)

docs/channels/qqbot.md

@@ -209,3 +209,9 @@ Approval prompts generated by the bot itself (for example, "allow this action?"
 - **Proactive messages not arriving:** QQ may intercept bot-initiated messages if
   the user hasn't interacted recently.
 - **Voice not transcribed:** ensure STT is configured and the provider is reachable.
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Groups](/channels/groups)
+- [Channel troubleshooting](/channels/troubleshooting)

docs/channels/signal.md

@@ -99,7 +99,7 @@ Example:
 }
 ```
 
-Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels) for the shared pattern.
+Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/config-channels#multi-account-all-channels) for the shared pattern.
 
 ## Setup path B: register dedicated bot number (SMS, Linux)
 

docs/channels/slack.md

@@ -785,7 +785,7 @@ Same-chat `/approve` also works in Slack channels and DMs that already support c
 
 ## Configuration reference
 
-Primary reference: [Configuration reference - Slack](/gateway/configuration-reference#slack).
+Primary reference: [Configuration reference - Slack](/gateway/config-channels#slack).
 
 <Accordion title="High-signal Slack fields">
 

docs/channels/telegram.md

@@ -885,7 +885,7 @@ More help: [Channel troubleshooting](/channels/troubleshooting).
 
 ## Configuration reference
 
-Primary reference: [Configuration reference - Telegram](/gateway/configuration-reference#telegram).
+Primary reference: [Configuration reference - Telegram](/gateway/config-channels#telegram).
 
 <Accordion title="High-signal Telegram fields">
 

docs/channels/troubleshooting.md

@@ -131,3 +131,9 @@ Full troubleshooting: [QQ Bot troubleshooting](/channels/qqbot#troubleshooting)
 | Cross-signing/bootstrap looks wrong | `openclaw matrix verify bootstrap`     | Repair secret storage, cross-signing, and backup state in one pass.       |
 
 Full setup and config: [Matrix](/channels/matrix)
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/channels/whatsapp.md

@@ -558,7 +558,7 @@ Example:
 
 Primary reference:
 
-- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp)
+- [Configuration reference - WhatsApp](/gateway/config-channels#whatsapp)
 
 High-signal WhatsApp fields:
 

docs/ci.md

@@ -23,17 +23,28 @@ listed PRs when `apply=true`. Before mutating GitHub, it verifies that the
 landed PR is merged and that each duplicate has either a shared referenced issue
 or overlapping changed hunks.
 
+The `Docs Agent` workflow is an event-driven Codex maintenance lane for keeping
+existing docs aligned with recently landed changes. It has no pure schedule: a
+successful non-bot push CI run on `main` can trigger it, and manual dispatch can
+run it directly. Workflow-run invocations skip when `main` has moved on or when
+another non-skipped Docs Agent run was created in the last hour. When it runs, it
+reviews the commit range from the previous non-skipped Docs Agent source SHA to
+current `main`, so one hourly run can cover all main changes accumulated since
+the last docs pass.
+
 The `Test Performance Agent` workflow is an event-driven Codex maintenance lane
 for slow tests. It has no pure schedule: a successful non-bot push CI run on
 `main` can trigger it, but it skips if another workflow-run invocation already
 ran or is running that UTC day. Manual dispatch bypasses that daily activity
 gate. The lane builds a full-suite grouped Vitest performance report, lets Codex
-make only small coverage-preserving test performance fixes, then reruns the
-full-suite report and rejects changes that reduce the passing baseline test
-count. If the baseline has failing tests, Codex may fix only obvious failures
-and the after-agent full-suite report must pass before anything is committed.
-It uses GitHub-hosted Ubuntu so the Codex action can keep the same drop-sudo
-safety posture as the docs agent.
+make only small coverage-preserving test performance fixes instead of broad
+refactors, then reruns the full-suite report and rejects changes that reduce the
+passing baseline test count. If the baseline has failing tests, Codex may fix
+only obvious failures and the after-agent full-suite report must pass before
+anything is committed. When `main` advances before the bot push lands, the lane
+rebases the validated patch, reruns `pnpm check:changed`, and retries the push;
+conflicting stale patches are skipped. It uses GitHub-hosted Ubuntu so the Codex
+action can keep the same drop-sudo safety posture as the docs agent.
 
 ```bash
 gh workflow run duplicate-after-merge.yml \
@@ -80,7 +91,7 @@ Jobs are ordered so cheap checks fail before expensive ones run:
 Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.
 CI workflow edits validate the Node CI graph plus workflow linting, but do not force Windows, Android, or macOS native builds by themselves; those platform lanes stay scoped to platform source changes.
 Windows Node checks are scoped to Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config, and the CI workflow surfaces that execute that lane; unrelated source, plugin, install-smoke, and test-only changes stay on the Linux Node lanes so they do not reserve a 16-vCPU Windows worker for coverage that is already exercised by the normal test shards.
-The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It computes `run_install_smoke` from the narrower changed-smoke signal, so Docker/install smoke runs for install, packaging, container-relevant changes, bundled extension production changes, and the core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Test-only and docs-only edits do not reserve Docker workers. Its QR package smoke forces the Docker `pnpm install` layer to rerun while preserving the BuildKit pnpm store cache, so it still exercises installation without redownloading dependencies on every run. Its gateway-network e2e reuses the runtime image built earlier in the job, so it adds real container-to-container WebSocket coverage without adding another Docker build. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes in parallel with `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default concurrency of 4 with `OPENCLAW_DOCKER_ALL_PARALLELISM`. The local aggregate stops scheduling new pooled lanes after the first failure by default, and each lane has a 120-minute timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Startup- or provider-sensitive lanes run exclusively after the parallel pool. The reusable live/E2E workflow mirrors the shared-image pattern by building and pushing one SHA-tagged GHCR Docker E2E image before the Docker matrix, then running the matrix with `OPENCLAW_SKIP_DOCKER_BUILD=1`. The scheduled live/E2E workflow runs the full release-path Docker suite daily. QR and installer Docker tests keep their own install-focused Dockerfiles. A separate `docker-e2e-fast` job runs the bounded bundled-plugin Docker profile under a 120-second command timeout: setup-entry dependency repair plus synthetic bundled-loader failure isolation. The full bundled update/channel matrix remains manual/full-suite because it performs repeated real npm update and doctor repair passes.
+The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It splits smoke coverage into `run_fast_install_smoke` and `run_full_install_smoke`. Pull requests run the fast path for Docker/package surfaces, bundled plugin package/manifest changes, and core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 120-second command timeout. The full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. `main` pushes, including merge commits, do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation. The slow Bun global install image-provider smoke is separately gated by `run_bun_global_install_smoke`; it runs on the nightly schedule and from the release checks workflow, and manual `install-smoke` dispatches can opt into it, but pull requests and `main` pushes do not run it. QR and installer Docker tests keep their own install-focused Dockerfiles. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes in parallel with `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default concurrency of 4 with `OPENCLAW_DOCKER_ALL_PARALLELISM`. The local aggregate stops scheduling new pooled lanes after the first failure by default, and each lane has a 120-minute timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Startup- or provider-sensitive lanes run exclusively after the parallel pool. The reusable live/E2E workflow mirrors the shared-image pattern by building and pushing one SHA-tagged GHCR Docker E2E image before the Docker matrix, then running the matrix with `OPENCLAW_SKIP_DOCKER_BUILD=1`. The scheduled live/E2E workflow runs the full release-path Docker suite daily. The full bundled update/channel matrix remains manual/full-suite because it performs repeated real npm update and doctor repair passes.
 
 Local changed-lane logic lives in `scripts/changed-lanes.mjs` and is executed by `scripts/check-changed.mjs`. That local gate is stricter about architecture boundaries than the broad CI platform scope: core production changes run core prod typecheck plus core tests, core test-only changes run only core test typecheck/tests, extension production changes run extension prod typecheck plus extension tests, and extension test-only changes run only extension test typecheck/tests. Public Plugin SDK or plugin-contract changes expand to extension validation because extensions depend on those core contracts. Release metadata-only version bumps run targeted version/config/root-dependency checks. Unknown root/config changes fail safe to all lanes.
 

docs/cli/acp.md

@@ -167,8 +167,8 @@ error instead of silently ignoring them.
 If you want ACPX-backed sessions to see OpenClaw plugin tools or selected
 built-in tools such as `cron`, enable the gateway-side ACPX MCP bridges instead
 of trying to pass per-session `mcpServers`. See
-[ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge) and
-[OpenClaw tools MCP bridge](/tools/acp-agents#openclaw-tools-mcp-bridge).
+[ACP Agents](/tools/acp-agents-setup#plugin-tools-mcp-bridge) and
+[OpenClaw tools MCP bridge](/tools/acp-agents-setup#openclaw-tools-mcp-bridge).
 
 ## Use from `acpx` (Codex, Claude, other ACP clients)
 

docs/cli/agent.md

@@ -55,3 +55,8 @@ openclaw agent --agent ops --message "Run locally" --local
 - `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing.
 - When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext.
 - Marker writes are source-authoritative: OpenClaw persists markers from the active source config snapshot, not from resolved runtime secret values.
+
+## Related
+
+- [CLI reference](/cli)
+- [Agent runtime](/concepts/agent)

docs/cli/agents.md

@@ -37,7 +37,7 @@ Use routing bindings to pin inbound channel traffic to a specific agent.
 If you also want different visible skills per agent, configure
 `agents.defaults.skills` and `agents.list[].skills` in `openclaw.json`. See
 [Skills config](/tools/skills-config) and
-[Configuration Reference](/gateway/configuration-reference#agents-defaults-skills).
+[Configuration Reference](/gateway/config-agents#agents-defaults-skills).
 
 List bindings:
 
@@ -218,3 +218,9 @@ Config sample:
   },
 }
 ```
+
+## Related
+
+- [CLI reference](/cli)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Agent workspace](/concepts/agent-workspace)

docs/cli/approvals.md

@@ -183,3 +183,8 @@ Targeting notes:
 - `--agent` defaults to `"*"`, which applies to all agents.
 - The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
 - Approvals files are stored per host at `~/.openclaw/exec-approvals.json`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Exec approvals](/tools/exec-approvals)

docs/cli/channels.md

@@ -129,3 +129,8 @@ Notes:
 - Use `--kind user|group|auto` to force the target type.
 - Resolution prefers active matches when multiple entries share the same name.
 - `channels resolve` is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.
+
+## Related
+
+- [CLI reference](/cli)
+- [Channels overview](/channels)

docs/cli/config.md

@@ -38,7 +38,7 @@ openclaw config get browser.executablePath
 openclaw config set browser.executablePath "/usr/bin/google-chrome"
 openclaw config set agents.defaults.heartbeat.every "2h"
 openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
-openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge
+openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
 openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
 openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
 openclaw config unset plugins.entries.brave.config.webSearch.apiKey
@@ -115,7 +115,7 @@ you pass `--replace`.
 Use `--merge` when adding entries to those maps:
 
 ```bash
-openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge
+openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
 openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
 ```
 
@@ -428,3 +428,8 @@ Typical repair loop:
 - Apply targeted edits with `openclaw config set` or `openclaw configure`.
 - Rerun `openclaw config validate` after each change.
 - If validation passes but the runtime is still unhealthy, run `openclaw doctor` or `openclaw doctor --fix` for migration and repair help.
+
+## Related
+
+- [CLI reference](/cli)
+- [Configuration](/gateway/configuration)

docs/cli/hooks.md

@@ -15,7 +15,7 @@ Running `openclaw hooks` with no subcommand is equivalent to `openclaw hooks lis
 Related:
 
 - Hooks: [Hooks](/automation/hooks)
-- Plugin hooks: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
+- Plugin hooks: [Plugin hooks](/plugins/architecture-internals#provider-runtime-hooks)
 
 ## List All Hooks
 
@@ -336,3 +336,8 @@ openclaw hooks enable boot-md
 ```
 
 **See:** [boot-md documentation](/automation/hooks#boot-md)
+
+## Related
+
+- [CLI reference](/cli)
+- [Automation hooks](/automation/hooks)

docs/cli/infer.md

@@ -121,7 +121,7 @@ This table maps common inference tasks to the corresponding infer command.
 - Use `--json` when the output will be consumed by another command or script.
 - Use `--provider` or `--model provider/model` when a specific backend is required.
 - For `image describe`, `audio transcribe`, and `video describe`, `--model` must use the form `<provider/model>`.
-- For `image describe`, an explicit `--model` runs that provider/model directly. The model must be image-capable in the model catalog or provider config.
+- For `image describe`, an explicit `--model` runs that provider/model directly. The model must be image-capable in the model catalog or provider config. `codex/<model>` runs a bounded Codex app-server image-understanding turn; `openai-codex/<model>` uses the OpenAI Codex OAuth provider path.
 - Stateless execution commands default to local.
 - Gateway-managed state commands default to gateway.
 - The normal local path does not require the gateway to be running.
@@ -279,3 +279,8 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
 ## Notes
 
 - `openclaw capability ...` is an alias for `openclaw infer ...`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Models](/concepts/models)

docs/cli/mcp.md

@@ -516,3 +516,8 @@ Current limits:
 - HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
 - `permissions_list_open` only includes approvals observed while the bridge is
   connected
+
+## Related
+
+- [CLI reference](/cli)
+- [Plugins](/cli/plugins)

docs/cli/models.md

@@ -44,6 +44,9 @@ Probe rows can come from auth profiles, env credentials, or `models.json`.
 Notes:
 
 - `models set <model-or-alias>` accepts `provider/model` or an alias.
+- `models list` is read-only: it reads config, auth profiles, existing catalog
+  state, and provider-owned catalog rows, but it does not rewrite
+  `models.json`.
 - `models list --all` includes bundled provider-owned static catalog rows even
   when you have not authenticated with that provider yet. Those rows still show
   as unavailable until matching auth is configured.
@@ -139,3 +142,9 @@ Notes:
   relative duration such as `365d` or `12h`.
 - Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
 - Anthropic `setup-token` / `paste-token` remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
+
+## Related
+
+- [CLI reference](/cli)
+- [Model selection](/concepts/model-providers)
+- [Model failover](/concepts/model-failover)

docs/cli/nodes.md

@@ -64,3 +64,8 @@ Invoke flags:
 For shell execution on a node, use the `exec` tool with `host=node` instead of `openclaw nodes run`.
 The `nodes` CLI is now capability-focused: direct RPC via `nodes invoke`, plus pairing, camera,
 screen, location, canvas, and notifications.
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

docs/cli/pairing.md

@@ -63,3 +63,8 @@ Options:
 - `pairing list` supports `--account <accountId>` for multi-account channels.
 - `pairing approve` supports `--account <accountId>` and `--notify`.
 - If only one pairing-capable channel is configured, `pairing approve <code>` is allowed.
+
+## Related
+
+- [CLI reference](/cli)
+- [Channel pairing](/channels/pairing)

docs/cli/plugins.md

@@ -327,3 +327,9 @@ Marketplace list accepts a local marketplace path, a `marketplace.json` path, a
 GitHub shorthand like `owner/repo`, a GitHub repo URL, or a git URL. `--json`
 prints the resolved source label plus the parsed marketplace manifest and
 plugin entries.
+
+## Related
+
+- [CLI reference](/cli)
+- [Building plugins](/plugins/building-plugins)
+- [Community plugins](/plugins/community)

docs/cli/sandbox.md

@@ -193,3 +193,8 @@ Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sand
 - [Sandbox Documentation](/gateway/sandboxing)
 - [Agent Configuration](/concepts/agent-workspace)
 - [Doctor Command](/gateway/doctor) - Check sandbox setup
+
+## Related
+
+- [CLI reference](/cli)
+- [Sandboxing](/gateway/sandboxing)

docs/cli/sessions.md

@@ -110,4 +110,9 @@ openclaw sessions cleanup --json
 
 Related:
 
-- Session config: [Configuration reference](/gateway/configuration-reference#session)
+- Session config: [Configuration reference](/gateway/config-agents#session)
+
+## Related
+
+- [CLI reference](/cli)
+- [Session management](/concepts/session)

docs/cli/skills.md

@@ -57,3 +57,8 @@ Notes:
 - `list`, `info`, and `check` write their rendered output to stdout. With
   `--json`, that means the machine-readable payload stays on stdout for pipes
   and scripts.
+
+## Related
+
+- [CLI reference](/cli)
+- [Skills](/tools/skills)

docs/cli/status.md

@@ -34,3 +34,8 @@ Notes:
 - If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as “configured token unavailable in this command path”, and JSON output includes `secretDiagnostics`.
 - When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient “secret unavailable” channel markers from the final output.
 - `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.
+
+## Related
+
+- [CLI reference](/cli)
+- [Doctor](/gateway/doctor)

docs/cli/update.md

@@ -120,7 +120,7 @@ If pnpm bootstrap still fails, the updater now stops early with a package-manage
 
 `openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts).
 
-## See also
+## Related
 
 - `openclaw doctor` (offers to run update first on git checkouts)
 - [Development channels](/install/development-channels)

docs/cli/voicecall.md

@@ -2,7 +2,7 @@
 summary: "CLI reference for `openclaw voicecall` (voice-call plugin command surface)"
 read_when:
   - You use the voice-call plugin and want the CLI entry points
-  - You want quick examples for `voicecall call|continue|status|tail|expose`
+  - You want quick examples for `voicecall call|continue|dtmf|status|tail|expose`
 title: "Voicecall"
 ---
 
@@ -20,6 +20,7 @@ Primary doc:
 openclaw voicecall status --call-id <id>
 openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
 openclaw voicecall continue --call-id <id> --message "Any questions?"
+openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
 openclaw voicecall end --call-id <id>
 ```
 

docs/concepts/agent-loop.md

@@ -98,7 +98,7 @@ These run inside the agent loop or gateway pipeline:
 - **`before_compaction` / `after_compaction`**: observe or annotate compaction cycles.
 - **`before_tool_call` / `after_tool_call`**: intercept tool params/results.
 - **`before_install`**: inspect built-in scan findings and optionally block skill or plugin installs.
-- **`tool_result_persist`**: synchronously transform tool results before they are written to the session transcript.
+- **`tool_result_persist`**: synchronously transform tool results before they are written to an OpenClaw-owned session transcript.
 - **`message_received` / `message_sending` / `message_sent`**: inbound + outbound message hooks.
 - **`session_start` / `session_end`**: session lifecycle boundaries.
 - **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
@@ -112,7 +112,11 @@ Hook decision rules for outbound/tool guards:
 - `message_sending`: `{ cancel: true }` is terminal and stops lower-priority handlers.
 - `message_sending`: `{ cancel: false }` is a no-op and does not clear a prior cancel.
 
-See [Plugin hooks](/plugins/architecture#provider-runtime-hooks) for the hook API and registration details.
+See [Plugin hooks](/plugins/architecture-internals#provider-runtime-hooks) for the hook API and registration details.
+
+Harnesses may adapt these hooks differently. The Codex app-server harness keeps
+OpenClaw plugin hooks as the compatibility contract for documented mirrored
+surfaces, while Codex native hooks remain a separate lower-level Codex mechanism.
 
 ## Streaming + partial replies
 

docs/concepts/agent-workspace.md

@@ -90,7 +90,7 @@ These are the standard files OpenClaw expects inside the workspace:
   - Keep it short to avoid token burn.
 
 - `BOOT.md`
-  - Optional startup checklist executed on gateway restart when internal hooks are enabled.
+  - Optional startup checklist run automatically on gateway restart (when [internal hooks](/automation/hooks) are enabled).
   - Keep it short; use the message tool for outbound sends.
 
 - `BOOTSTRAP.md`

docs/concepts/agent.md

@@ -125,3 +125,9 @@ At minimum, set:
 ---
 
 _Next: [Group Chats](/channels/group-messages)_ 🦞
+
+## Related
+
+- [Agent workspace](/concepts/agent-workspace)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Session management](/concepts/session)

docs/concepts/compaction.md

@@ -113,6 +113,20 @@ the summary:
 /compact Focus on the API design decisions
 ```
 
+## Codex harness compaction
+
+When an embedded agent session uses the Codex app-server harness, Codex owns the
+native thread and native compaction operation. OpenClaw keeps a transcript mirror
+for channel history and future harness switching, but the canonical compacted
+thread stays in Codex.
+
+OpenClaw plugin hooks still expose `before_compaction` and `after_compaction`
+for the Codex harness from the app-server compaction item stream. Codex native
+`PreCompact` and `PostCompact` hooks, when supported by the installed Codex
+app-server, are separate Codex command hooks configured through Codex. They are
+useful for low-level Codex audit or policy, but they do not replace the
+OpenClaw plugin hook contract.
+
 ## Using a different model
 
 By default, compaction uses your agent's primary model. You can use a more

docs/concepts/context-engine.md

@@ -7,12 +7,13 @@ read_when:
 title: "Context engine"
 ---
 
-A **context engine** controls how OpenClaw builds model context for each run.
-It decides which messages to include, how to summarize older history, and how
-to manage context across subagent boundaries.
+A **context engine** controls how OpenClaw builds model context for each run:
+which messages to include, how to summarize older history, and how to manage
+context across subagent boundaries.
 
-OpenClaw ships with a built-in `legacy` engine. Plugins can register
-alternative engines that replace the active context-engine lifecycle.
+OpenClaw ships with a built-in `legacy` engine and uses it by default — most
+users never need to change this. Install and select a plugin engine only when
+you want different assembly, compaction, or cross-session recall behavior.
 
 ## Quick start
 

docs/concepts/delegate-architecture.md

@@ -303,3 +303,9 @@ The delegate model works for any small organization:
 6. **Review and adjust** the capability tier as trust builds.
 
 Multiple organizations can share one Gateway server using multi-agent routing — each org gets its own isolated agent, workspace, and credentials.
+
+## Related
+
+- [Agent runtime](/concepts/agent)
+- [Sub-agents](/tools/subagents)
+- [Multi-agent routing](/concepts/multi-agent)

docs/concepts/experimental-features.md

@@ -43,3 +43,8 @@ If a feature is experimental, OpenClaw should say so plainly in docs and in the
 config path itself. What it should **not** do is smuggle preview behavior into a
 stable-looking default knob and pretend that is normal. That's how config
 surfaces get messy.
+
+## Related
+
+- [Features](/concepts/features)
+- [Release channels](/install/development-channels)

docs/concepts/features.md

@@ -72,3 +72,8 @@ title: "Features"
 - Web search (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily)
 - Cron jobs and heartbeat scheduling
 - Skills, plugins, and workflow pipelines (Lobster)
+
+## Related
+
+- [Experimental features](/concepts/experimental-features)
+- [Agent runtime](/concepts/agent)

docs/concepts/markdown-formatting.md

@@ -126,3 +126,8 @@ SPOILER style ranges. Other channels treat them as plain text.
 - Signal style ranges depend on UTF-16 offsets; do not use code point offsets.
 - Preserve trailing newlines for fenced code blocks so closing markers land on
   their own line.
+
+## Related
+
+- [Streaming and chunking](/concepts/streaming)
+- [System prompt](/concepts/system-prompt)

docs/concepts/memory-builtin.md

@@ -38,6 +38,25 @@ To set a provider explicitly:
 
 Without an embedding provider, only keyword search is available.
 
+To force the built-in local embedding provider, point `local.modelPath` at a
+GGUF file:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "local",
+        fallback: "none",
+        local: {
+          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",
+        },
+      },
+    },
+  },
+}
+```
+
 ## Supported embedding providers
 
 | Provider | ID        | Auto-detected | Notes                               |
@@ -89,6 +108,17 @@ automatic user modeling.
 **Memory search disabled?** Check `openclaw memory status`. If no provider is
 detected, set one explicitly or add an API key.
 
+**Local provider not detected?** Confirm the local path exists and run:
+
+```bash
+openclaw memory status --deep --agent main
+openclaw memory index --force --agent main
+```
+
+Both standalone CLI commands and the Gateway use the same `local` provider id.
+If the provider is set to `auto`, local embeddings are considered first only
+when `memorySearch.local.modelPath` points to an existing local file.
+
 **Stale results?** Run `openclaw memory index --force` to rebuild. The watcher
 may miss changes in rare edge cases.
 
@@ -101,3 +131,9 @@ For embedding provider setup, hybrid search tuning (weights, MMR, temporal
 decay), batch indexing, multimodal memory, sqlite-vec, extra paths, and all
 other config knobs, see the
 [Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Memory search](/concepts/memory-search)
+- [Active memory](/concepts/active-memory)

docs/concepts/memory-honcho.md

@@ -136,3 +136,9 @@ openclaw honcho search <query> [-k N] [-d D] # Semantic search over memory
 - [Honcho OpenClaw integration guide](https://docs.honcho.dev/v3/guides/integrations/openclaw)
 - [Memory](/concepts/memory) -- OpenClaw memory overview
 - [Context Engines](/concepts/context-engine) -- how plugin context engines work
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [QMD memory engine](/concepts/memory-qmd)

docs/concepts/memory-qmd.md

@@ -43,6 +43,9 @@ OpenClaw creates a self-contained QMD home under
 automatically -- collections, updates, and embedding runs are handled for you.
 It prefers current QMD collection and MCP query shapes, but still falls back to
 legacy `--mask` collection flags and older MCP tool names when needed.
+Boot-time reconciliation also recreates stale managed collections back to their
+canonical patterns when an older QMD collection with the same name is still
+present.
 
 ## How the sidecar works
 
@@ -166,6 +169,11 @@ Set to `120000` for slower hardware.
 **Empty results in group chats?** Check `memory.qmd.scope` -- the default only
 allows direct and channel sessions.
 
+**Root memory search suddenly got too broad?** Restart the gateway or wait for
+the next startup reconciliation. OpenClaw recreates stale managed collections
+back to canonical `MEMORY.md` and `memory/` patterns when it detects a same-name
+conflict.
+
 **Workspace-visible temp repos causing `ENAMETOOLONG` or broken indexing?**
 QMD traversal currently follows the underlying QMD scanner behavior rather than
 OpenClaw's builtin symlink rules. Keep temporary monorepo checkouts under
@@ -177,3 +185,9 @@ cycle-safe traversal or explicit exclusion controls.
 For the full config surface (`memory.qmd.*`), search modes, update intervals,
 scope rules, and all other knobs, see the
 [Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [Honcho memory](/concepts/memory-honcho)

docs/concepts/memory-search.md

@@ -143,3 +143,9 @@ earlier conversations. This is opt-in via
 - [Active Memory](/concepts/active-memory) -- sub-agent memory for interactive chat sessions
 - [Memory](/concepts/memory) -- file layout, backends, tools
 - [Memory configuration reference](/reference/memory-config) -- all config knobs
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Active memory](/concepts/active-memory)
+- [Builtin memory engine](/concepts/memory-builtin)

docs/concepts/memory.md

@@ -186,3 +186,10 @@ openclaw memory index --force   # Rebuild the index
   from short-term recall to long-term memory
 - [Memory configuration reference](/reference/memory-config) -- all config knobs
 - [Compaction](/concepts/compaction) -- how compaction interacts with memory
+
+## Related
+
+- [Active memory](/concepts/active-memory)
+- [Memory search](/concepts/memory-search)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [Honcho memory](/concepts/memory-honcho)

docs/concepts/messages.md

@@ -149,7 +149,7 @@ Outbound message formatting is centralized in `messages`:
 - `messages.responsePrefix`, `channels.<channel>.responsePrefix`, and `channels.<channel>.accounts.<id>.responsePrefix` (outbound prefix cascade), plus `channels.whatsapp.messagePrefix` (WhatsApp inbound prefix)
 - Reply threading via `replyToMode` and per-channel defaults
 
-Details: [Configuration](/gateway/configuration-reference#messages) and channel docs.
+Details: [Configuration](/gateway/config-agents#messages) and channel docs.
 
 ## Silent replies
 

docs/concepts/model-providers.md

@@ -16,7 +16,16 @@ For model selection rules, see [/concepts/models](/concepts/models).
 - CLI helpers: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
 - `models.providers.*.models[].contextWindow` is native model metadata; `contextTokens` is the effective runtime cap.
 - Fallback rules, cooldown probes, and session-override persistence: [Model failover](/concepts/model-failover).
-- OpenAI GPT model refs are canonical as `openai/<model>`. Legacy `openai-codex/<model>` and `codex/<model>` refs remain compatibility aliases for older configs and tests. For native Codex app-server execution, keep the model ref as `openai/gpt-*` and force `agents.defaults.embeddedHarness.runtime: "codex"` — see [Codex harness](/plugins/codex-harness).
+- OpenAI-family routes are prefix-specific: `openai/<model>` uses the direct
+  OpenAI API-key provider in PI, `openai-codex/<model>` uses Codex OAuth in PI,
+  and `openai/<model>` plus `agents.defaults.embeddedHarness.runtime: "codex"`
+  uses the native Codex app-server harness. See [OpenAI](/providers/openai)
+  and [Codex harness](/plugins/codex-harness).
+- GPT-5.5 is currently available through subscription/OAuth routes:
+  `openai-codex/gpt-5.5` in PI or `openai/gpt-5.5` with the Codex app-server
+  harness. The direct API-key route for `openai/gpt-5.5` is supported once
+  OpenAI enables GPT-5.5 on the public API; until then use API-enabled models
+  such as `openai/gpt-5.4` for `OPENAI_API_KEY` setups.
 
 ## Plugin-owned provider behavior
 
@@ -55,7 +64,8 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - Provider: `openai`
 - Auth: `OPENAI_API_KEY`
 - Optional rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (single override)
-- Example models: `openai/gpt-5.5`, `openai/gpt-5.5-pro`
+- Example models: `openai/gpt-5.4`, `openai/gpt-5.4-mini`
+- GPT-5.5 direct API support is future-ready here once OpenAI exposes GPT-5.5 on the API
 - CLI: `openclaw onboard --auth-choice openai-api-key`
 - Default transport is `auto` (WebSocket-first, SSE fallback)
 - Override per model via `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)
@@ -72,7 +82,7 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
+  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
 }
 ```
 
@@ -97,22 +107,24 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 
 - Provider: `openai-codex`
 - Auth: OAuth (ChatGPT)
-- Canonical model ref: `openai/gpt-5.5`
-- Legacy model refs: `openai-codex/gpt-*`, `codex/gpt-*`
+- PI model ref: `openai-codex/gpt-5.5`
+- Native Codex app-server harness ref: `openai/gpt-5.5` with `agents.defaults.embeddedHarness.runtime: "codex"`
+- Legacy model refs: `codex/gpt-*`
 - CLI: `openclaw onboard --auth-choice openai-codex` or `openclaw models auth login --provider openai-codex`
 - Default transport is `auto` (WebSocket-first, SSE fallback)
-- Override per model via `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)
+- Override per PI model via `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)
 - `params.serviceTier` is also forwarded on native Codex Responses requests (`chatgpt.com/backend-api`)
 - Hidden OpenClaw attribution headers (`originator`, `version`,
   `User-Agent`) are only attached on native Codex traffic to
   `chatgpt.com/backend-api`, not generic OpenAI-compatible proxies
 - Shares the same `/fast` toggle and `params.fastMode` config as direct `openai/*`; OpenClaw maps that to `service_tier=priority`
-- `openai/gpt-5.5` keeps native `contextWindow = 1000000` and a default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens`
+- `openai-codex/gpt-5.5` keeps native `contextWindow = 1000000` and a default runtime `contextTokens = 272000`; override the runtime cap with `models.providers.openai-codex.models[].contextTokens`
 - Policy note: OpenAI Codex OAuth is explicitly supported for external tools/workflows like OpenClaw.
+- Current GPT-5.5 access uses this OAuth/subscription route until OpenAI enables GPT-5.5 on the public API.
 
 ```json5
 {
-  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
+  agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
 }
 ```
 
@@ -618,5 +630,5 @@ See also: [/gateway/configuration](/gateway/configuration) for full configuratio
 
 - [Models](/concepts/models) — model configuration and aliases
 - [Model Failover](/concepts/model-failover) — fallback chains and retry behavior
-- [Configuration Reference](/gateway/configuration-reference#agent-defaults) — model config keys
+- [Configuration Reference](/gateway/config-agents#agent-defaults) — model config keys
 - [Providers](/providers) — per-provider setup guides

docs/concepts/models.md

@@ -70,7 +70,7 @@ Provider configuration examples (including OpenCode) live in
 Use additive writes when updating `agents.defaults.models` by hand:
 
 ```bash
-openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge
+openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
 ```
 
 `openclaw config set` protects model/provider maps from accidental clobbers. A
@@ -122,7 +122,7 @@ You can switch models for the current session without restarting:
 /model
 /model list
 /model 3
-/model openai/gpt-5.5
+/model openai/gpt-5.4
 /model status
 ```
 
@@ -288,4 +288,4 @@ This applies whenever OpenClaw regenerates `models.json`, including command-driv
 - [Image Generation](/tools/image-generation) — image model configuration
 - [Music Generation](/tools/music-generation) — music model configuration
 - [Video Generation](/tools/video-generation) — video model configuration
-- [Configuration Reference](/gateway/configuration-reference#agent-defaults) — model config keys
+- [Configuration Reference](/gateway/config-agents#agent-defaults) — model config keys

docs/concepts/multi-agent.md

@@ -5,7 +5,9 @@ read_when: "You want multiple isolated agents (workspaces + auth) in one gateway
 status: active
 ---
 
-Goal: multiple _isolated_ agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
+Run multiple _isolated_ agents — each with its own workspace, state directory (`agentDir`), and session history — plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound messages are routed to the right agent through bindings.
+
+An **agent** here is the full per-persona scope: workspace files, auth profiles, model registry, and session store. `agentDir` is the on-disk state directory that holds this per-agent config at `~/.openclaw/agents/<agentId>/`. A **binding** maps a channel account (e.g. a Slack workspace or a WhatsApp number) to one of those agents.
 
 ## What is "one agent"?
 

docs/concepts/presence.md

@@ -98,3 +98,8 @@ indicator (Active/Idle/Stale) based on the age of the last update.
   - confirm clients send a stable `client.instanceId` in the handshake
   - confirm periodic beacons use the same `instanceId`
   - check whether the connection‑derived entry is missing `instanceId` (duplicates are expected)
+
+## Related
+
+- [Typing indicators](/concepts/typing-indicators)
+- [Streaming and chunking](/concepts/streaming)

docs/concepts/qa-e2e-automation.md

@@ -83,16 +83,34 @@ you want artifacts without a failing exit code.
 The Telegram report and summary include per-reply RTT from the driver message
 send request to the observed SUT reply, starting with the canary.
 
+For a transport-real Discord smoke lane, run:
+
+```bash
+pnpm openclaw qa discord
+```
+
+That lane targets one real private Discord guild channel with two bots: a
+driver bot controlled by the harness and a SUT bot started by the child
+OpenClaw gateway through the bundled Discord plugin. It requires
+`OPENCLAW_QA_DISCORD_GUILD_ID`, `OPENCLAW_QA_DISCORD_CHANNEL_ID`,
+`OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`,
+and `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` when using env credentials.
+The lane verifies channel mention handling and checks that the SUT bot has
+registered the native `/help` command with Discord.
+The command exits non-zero when any scenario fails. Use `--allow-failures` when
+you want artifacts without a failing exit code.
+
 Live transport lanes now share one smaller contract instead of each inventing
 their own scenario list shape:
 
 `qa-channel` remains the broad synthetic product-behavior suite and is not part
 of the live transport coverage matrix.
 
-| Lane     | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command |
-| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ |
-| Matrix   | x      | x              | x               | x               | x              | x                | x                | x                    |              |
-| Telegram | x      |                |                 |                 |                |                  |                  |                      | x            |
+| Lane     | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | Native command registration |
+| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- |
+| Matrix   | x      | x              | x               | x               | x              | x                | x                | x                    |              |                             |
+| Telegram | x      | x              |                 |                 |                |                  |                  |                      | x            |                             |
+| Discord  | x      | x              |                 |                 |                |                  |                  |                      |              | x                           |
 
 This keeps `qa-channel` as the broad product-behavior suite while Matrix,
 Telegram, and future live transports share one explicit transport-contract
@@ -207,7 +225,7 @@ refs and write a judged Markdown report:
 
 ```bash
 pnpm openclaw qa character-eval \
-  --model openai/gpt-5.5,thinking=xhigh \
+  --model openai/gpt-5.4,thinking=medium,fast \
   --model openai/gpt-5.2,thinking=xhigh \
   --model openai/gpt-5,thinking=xhigh \
   --model anthropic/claude-opus-4-6,thinking=high \
@@ -215,7 +233,7 @@ pnpm openclaw qa character-eval \
   --model zai/glm-5.1,thinking=high \
   --model moonshot/kimi-k2.5,thinking=high \
   --model google/gemini-3.1-pro-preview,thinking=high \
-  --judge-model openai/gpt-5.5,thinking=xhigh,fast \
+  --judge-model openai/gpt-5.4,thinking=xhigh,fast \
   --judge-model anthropic/claude-opus-4-6,thinking=high \
   --blind-judge-models \
   --concurrency 16 \
@@ -227,13 +245,13 @@ scenarios should set the persona through `SOUL.md`, then run ordinary user turns
 such as chat, workspace help, and small file tasks. The candidate model should
 not be told that it is being evaluated. The command preserves each full
 transcript, records basic run stats, then asks the judge models in fast mode with
-`xhigh` reasoning to rank the runs by naturalness, vibe, and humor.
+`xhigh` reasoning where supported to rank the runs by naturalness, vibe, and humor.
 Use `--blind-judge-models` when comparing providers: the judge prompt still gets
 every transcript and run status, but candidate refs are replaced with neutral
 labels such as `candidate-01`; the report maps rankings back to real refs after
 parsing.
-Candidate runs default to `high` thinking, with `xhigh` for OpenAI models that
-support it. Override a specific candidate inline with
+Candidate runs default to `high` thinking, with `medium` for GPT-5.4 and `xhigh`
+for older OpenAI eval refs that support it. Override a specific candidate inline with
 `--model provider/model,thinking=<level>`. `--thinking <level>` still sets a
 global fallback, and the older `--model-thinking <provider/model=level>` form is
 kept for compatibility.
@@ -247,12 +265,12 @@ Candidate and judge model runs both default to concurrency 16. Lower
 `--concurrency` or `--judge-concurrency` when provider limits or local gateway
 pressure make a run too noisy.
 When no candidate `--model` is passed, the character eval defaults to
-`openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
+`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
 `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
 `moonshot/kimi-k2.5`, and
 `google/gemini-3.1-pro-preview` when no `--model` is passed.
 When no `--judge-model` is passed, the judges default to
-`openai/gpt-5.5,thinking=xhigh,fast` and
+`openai/gpt-5.4,thinking=xhigh,fast` and
 `anthropic/claude-opus-4-6,thinking=high`.
 
 ## Related docs

docs/concepts/queue.md

@@ -87,3 +87,8 @@ Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
 
 - If commands seem stuck, enable verbose logs and look for “queued for …ms” lines to confirm the queue is draining.
 - If you need queue depth, enable verbose logs and watch for queue timing lines.
+
+## Related
+
+- [Session management](/concepts/session)
+- [Retry policy](/concepts/retry)