Add adaptive thinking resolution

Adds OpenRouter image generation support for image_generate. Fixes #55066. Thanks @notamicrodose.

.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/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,52 @@ 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' || github.event_name == 'push') && '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" ] && [ "$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_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 +139,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 +333,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 +364,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 +373,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/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,38 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- 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.
 - 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.
 
 ### Fixes
 
-- Agents/OpenAI: surface selected-model capacity failures with a model-switch hint instead of the generic empty-response error. Thanks @vincentkoc.
+- 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.
+- 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.
@@ -48,6 +61,8 @@ Docs: https://docs.openclaw.ai
 - 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
 

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

@@ -1,2 +1,2 @@
-bc55649a80027756f37892424598653a81fec4bff7b074358fe34d08c7696ebc  plugin-sdk-api-baseline.json
-312a29d50b4959e4a8e242bb7559548d895a2e03d5ed1b5a395b1133de090578  plugin-sdk-api-baseline.jsonl
+1d2767b688414ac41305e88c830858c00947e2d7c713f1a25d86f38cd577620e  plugin-sdk-api-baseline.json
+e5167477ab6aa2e67bd4361048cf5f6f8fd1cb7ee570544c634d14417f890674  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/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/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

@@ -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/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/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/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/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 `main` pushes, nightly scheduled runs, manual dispatches, workflow-call release checks, and true installer/package/Docker changes. 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 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/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
 ```
 

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.

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.

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-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/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

@@ -101,3 +101,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/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" } } },
 }
 ```
 

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
 ```
 

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

@@ -207,7 +207,7 @@ refs and write a judged Markdown report:
 
 ```bash
 pnpm openclaw qa character-eval \
-  --model openai/gpt-5.5,thinking=xhigh \
+  --model openai-codex/gpt-5.5,thinking=xhigh \
   --model openai/gpt-5.2,thinking=xhigh \
   --model openai/gpt-5,thinking=xhigh \
   --model anthropic/claude-opus-4-6,thinking=high \
@@ -215,7 +215,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-codex/gpt-5.5,thinking=xhigh,fast \
   --judge-model anthropic/claude-opus-4-6,thinking=high \
   --blind-judge-models \
   --concurrency 16 \
@@ -247,12 +247,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-codex/gpt-5.5`, `openai/gpt-5.4`, `openai/gpt-5.2`, `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-codex/gpt-5.5,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)

docs/concepts/retry.md

@@ -77,3 +77,8 @@ Set retry policy per provider in `~/.openclaw/openclaw.json`:
 
 - Retries apply per request (message send, media upload, reaction, poll, sticker).
 - Composite flows do not retry completed steps.
+
+## Related
+
+- [Model failover](/concepts/model-failover)
+- [Command queue](/concepts/queue)

docs/concepts/session-pruning.md

@@ -88,3 +88,9 @@ compaction cycles.
 - [Compaction](/concepts/compaction) -- summarization-based context reduction
 - [Gateway Configuration](/gateway/configuration) -- all pruning config knobs
   (`contextPruning.*`)
+
+## Related
+
+- [Session management](/concepts/session)
+- [Session tools](/concepts/session-tool)
+- [Context engine](/concepts/context-engine)

docs/concepts/session-tool.md

@@ -145,3 +145,8 @@ config.
 - [ACP Agents](/tools/acp-agents) -- external harness spawning
 - [Multi-agent](/concepts/multi-agent) -- multi-agent architecture
 - [Gateway Configuration](/gateway/configuration) -- session tool config knobs
+
+## Related
+
+- [Session management](/concepts/session)
+- [Session pruning](/concepts/session-pruning)

docs/concepts/session.md

@@ -116,3 +116,9 @@ Preview with `openclaw sessions cleanup --dry-run`.
 - [Multi-Agent](/concepts/multi-agent) — routing and session isolation across agents
 - [Background Tasks](/automation/tasks) — how detached work creates task records with session references
 - [Channel Routing](/channels/channel-routing) — how inbound messages are routed to sessions
+
+## Related
+
+- [Session pruning](/concepts/session-pruning)
+- [Session tools](/concepts/session-tool)
+- [Command queue](/concepts/queue)

docs/concepts/system-prompt.md

@@ -204,3 +204,9 @@ package docs) and also notes the public mirror, source repo, community Discord,
 ClawHub ([https://clawhub.ai](https://clawhub.ai)) for skills discovery. The prompt instructs the model to consult local docs first
 for OpenClaw behavior, commands, configuration, or architecture, and to run
 `openclaw status` itself when possible (asking the user only when it lacks access).
+
+## Related
+
+- [Agent runtime](/concepts/agent)
+- [Agent workspace](/concepts/agent-workspace)
+- [Context engine](/concepts/context-engine)

docs/concepts/typebox.md

@@ -305,3 +305,8 @@ published raw file is typically available at:
    node scope classification.
 4. Run `pnpm protocol:check`.
 5. Commit the regenerated schema + Swift models.
+
+## Related
+
+- [Rich output protocol](/reference/rich-output-protocol)
+- [RPC adapters](/reference/rpc)

docs/concepts/typing-indicators.md

@@ -71,3 +71,8 @@ You can override mode or cadence per session:
   channel does not support typing.
 - `typingIntervalSeconds` controls the **refresh cadence**, not the start time.
   The default is 6 seconds.
+
+## Related
+
+- [Presence](/concepts/presence)
+- [Streaming and chunking](/concepts/streaming)

docs/concepts/usage-tracking.md

@@ -55,3 +55,9 @@ Usage is hidden when no usable provider usage auth can be resolved. Providers
 can supply plugin-specific usage auth logic; otherwise OpenClaw falls back to
 matching OAuth/API-key credentials from auth profiles, environment variables,
 or config.
+
+## Related
+
+- [Token use and costs](/reference/token-use)
+- [API usage and costs](/reference/api-usage-costs)
+- [Prompt caching](/reference/prompt-caching)

docs/docs.json

@@ -1147,6 +1147,7 @@
                     "group": "SDK Reference",
                     "pages": [
                       "plugins/sdk-overview",
+                      "plugins/sdk-subpaths",
                       "plugins/sdk-entrypoints",
                       "plugins/sdk-runtime",
                       "plugins/sdk-agent-harness",
@@ -1189,6 +1190,7 @@
                   "tools/diffs",
                   "tools/elevated",
                   "tools/exec-approvals",
+                  "tools/exec-approvals-advanced",
                   "tools/exec",
                   "tools/image-generation",
                   "tools/llm-task",

docs/gateway/cli-backends.md

@@ -169,6 +169,15 @@ resolver sees the same filtered set that OpenClaw would otherwise advertise in
 the prompt. Skill env/API key overrides are still applied by OpenClaw to the
 child process environment for the run.
 
+Claude CLI also has its own noninteractive permission mode. OpenClaw maps that
+to the existing exec policy instead of adding Claude-specific config: when the
+effective requested exec policy is YOLO (`tools.exec.security: "full"` and
+`tools.exec.ask: "off"`), OpenClaw adds `--permission-mode bypassPermissions`.
+Per-agent `agents.list[].tools.exec` settings override global `tools.exec` for
+that agent. To force a different Claude mode, set explicit raw backend args
+such as `--permission-mode default` or `--permission-mode acceptEdits` under
+`agents.defaults.cliBackends.claude-cli.args` and matching `resumeArgs`.
+
 Before OpenClaw can use the bundled `claude-cli` backend, Claude Code itself
 must already be logged in on the same host:
 

docs/gateway/configuration-examples.md

@@ -234,7 +234,7 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
       userTimezone: "America/Chicago",
       model: {
         primary: "anthropic/claude-sonnet-4-6",
-        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.5"],
+        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
       },
       imageModel: {
         primary: "openrouter/anthropic/claude-sonnet-4-6",
@@ -242,7 +242,7 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
       models: {
         "anthropic/claude-opus-4-6": { alias: "opus" },
         "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
-        "openai/gpt-5.5": { alias: "gpt" },
+        "openai/gpt-5.4": { alias: "gpt" },
       },
       skills: ["github", "weather"], // inherited by agents that omit list[].skills
       thinkingDefault: "low",

docs/gateway/configuration-reference.md

@@ -1214,7 +1214,7 @@ Time format in system prompt. Default: `auto` (OS preference).
 - `imageGenerationModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the shared image-generation capability and any future tool/plugin surface that generates images.
   - Typical values: `google/gemini-3.1-flash-image-preview` for native Gemini image generation, `fal/fal-ai/flux/dev` for fal, or `openai/gpt-image-2` for OpenAI Images.
-  - If you select a provider/model directly, configure the matching provider auth/API key too (for example `GEMINI_API_KEY` or `GOOGLE_API_KEY` for `google/*`, `OPENAI_API_KEY` for `openai/*`, `FAL_KEY` for `fal/*`).
+  - If you select a provider/model directly, configure matching provider auth too (for example `GEMINI_API_KEY` or `GOOGLE_API_KEY` for `google/*`, `OPENAI_API_KEY` or OpenAI Codex OAuth for `openai/gpt-image-2`, `FAL_KEY` for `fal/*`).
   - If omitted, `image_generate` can still infer an auth-backed provider default. It tries the current default provider first, then the remaining registered image-generation providers in provider-id order.
 - `musicGenerationModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the shared music-generation capability and the built-in `music_generate` tool.
@@ -1234,7 +1234,7 @@ Time format in system prompt. Default: `auto` (OS preference).
 - `pdfMaxPages`: default maximum pages considered by extraction fallback mode in the `pdf` tool.
 - `verboseDefault`: default verbose level for agents. Values: `"off"`, `"on"`, `"full"`. Default: `"off"`.
 - `elevatedDefault`: default elevated-output level for agents. Values: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`.
-- `model.primary`: format `provider/model` (e.g. `openai/gpt-5.5`). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
+- `model.primary`: format `provider/model` (e.g. `openai/gpt-5.4` for API-key access or `openai-codex/gpt-5.5` for Codex OAuth). If you omit the provider, OpenClaw tries an alias first, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider (deprecated compatibility behavior, so prefer explicit `provider/model`). If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default.
 - `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
   - Safe edits: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` to add entries. `config set` refuses replacements that would remove existing allowlist entries unless you pass `--replace`.
   - Provider-scoped configure/onboarding flows merge selected provider models into this map and preserve unrelated providers already configured.
@@ -1274,16 +1274,16 @@ Codex app-server harness.
 
 **Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`):
 
-| Alias               | Model                                  |
-| ------------------- | -------------------------------------- |
-| `opus`              | `anthropic/claude-opus-4-6`            |
-| `sonnet`            | `anthropic/claude-sonnet-4-6`          |
-| `gpt`               | `openai/gpt-5.5`                       |
-| `gpt-mini`          | `openai/gpt-5.4-mini`                  |
-| `gpt-nano`          | `openai/gpt-5.4-nano`                  |
-| `gemini`            | `google/gemini-3.1-pro-preview`        |
-| `gemini-flash`      | `google/gemini-3-flash-preview`        |
-| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
+| Alias               | Model                                              |
+| ------------------- | -------------------------------------------------- |
+| `opus`              | `anthropic/claude-opus-4-6`                        |
+| `sonnet`            | `anthropic/claude-sonnet-4-6`                      |
+| `gpt`               | `openai/gpt-5.4` or configured Codex OAuth GPT-5.5 |
+| `gpt-mini`          | `openai/gpt-5.4-mini`                              |
+| `gpt-nano`          | `openai/gpt-5.4-nano`                              |
+| `gemini`            | `google/gemini-3.1-pro-preview`                    |
+| `gemini-flash`      | `google/gemini-3-flash-preview`                    |
+| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview`             |
 
 Your configured aliases always win over defaults.
 
@@ -2251,7 +2251,7 @@ Further restrict tools for specific providers or models. Order: base profile →
     profile: "coding",
     byProvider: {
       "google-antigravity": { profile: "minimal" },
-      "openai/gpt-5.5": { allow: ["group:fs", "sessions_list"] },
+      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
     },
   },
 }

docs/gateway/configuration.md

@@ -135,11 +135,11 @@ is skipped when a candidate contains redacted secret placeholders such as `***`.
         defaults: {
           model: {
             primary: "anthropic/claude-sonnet-4-6",
-            fallbacks: ["openai/gpt-5.5"],
+            fallbacks: ["openai/gpt-5.4"],
           },
           models: {
             "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
-            "openai/gpt-5.5": { alias: "GPT" },
+            "openai/gpt-5.4": { alias: "GPT" },
           },
         },
       },

docs/gateway/openai-http-api.md

@@ -169,7 +169,7 @@ This is the highest-leverage compatibility set for self-hosted frontends and too
     Use `x-openclaw-model`.
 
     Examples:
-    `x-openclaw-model: openai/gpt-5.5`
+    `x-openclaw-model: openai/gpt-5.4`
     `x-openclaw-model: gpt-5.5`
 
     If you omit it, the selected agent runs with its normal configured model choice.
@@ -237,7 +237,7 @@ Streaming:
 curl -N http://127.0.0.1:18789/v1/chat/completions \
   -H 'Authorization: Bearer YOUR_TOKEN' \
   -H 'Content-Type: application/json' \
-  -H 'x-openclaw-model: openai/gpt-5.5' \
+  -H 'x-openclaw-model: openai/gpt-5.4' \
   -d '{
     "model": "openclaw/research",
     "stream": true,

docs/gateway/openshell.md

@@ -303,7 +303,7 @@ the intended remote workspace.
 5. In `remote` mode: seed once on create, then operate directly on the remote
    workspace.
 
-## See also
+## Related
 
 - [Sandboxing](/gateway/sandboxing) -- modes, scopes, and backend comparison
 - [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging blocked tools

docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -65,7 +65,7 @@ Rules of thumb:
 - If `allow` is non-empty, everything else is treated as blocked.
 - Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
 - `/exec` only changes session defaults for authorized senders; it does not grant tool access.
-  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.5`).
+  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
 
 ### Tool groups (shorthands)
 
@@ -132,7 +132,7 @@ Fix-it keys (pick one):
 
 In `"non-main"` mode, group/channel keys are _not_ main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
 
-## See also
+## Related
 
 - [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
 - [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence

docs/help/faq.md

@@ -656,20 +656,29 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   </Accordion>
 
   <Accordion title="How does Codex auth work?">
-    OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). New model refs should use the canonical `openai/gpt-5.5` path; `openai-codex/gpt-*` remains a legacy compatibility alias. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
+    OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Use
+    `openai-codex/gpt-5.5` for Codex OAuth through the default PI runner. Use
+    `openai/gpt-5.4` for current direct OpenAI API-key access. GPT-5.5 direct
+    API-key access is supported once OpenAI enables it on the public API; today
+    GPT-5.5 uses subscription/OAuth via `openai-codex/gpt-5.5` or native Codex
+    app-server runs with `openai/gpt-5.5` and `embeddedHarness.runtime: "codex"`.
+    See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
   </Accordion>
 
   <Accordion title="Why does OpenClaw still mention openai-codex?">
-    `openai-codex` is still the internal auth/profile provider id for ChatGPT/Codex OAuth. The model ref should be canonical OpenAI:
+    `openai-codex` is the provider and auth-profile id for ChatGPT/Codex OAuth.
+    It is also the explicit PI model prefix for Codex OAuth:
 
-    - `openai/gpt-5.5` = canonical GPT-5.5 model ref
-    - `openai-codex/gpt-5.5` = legacy compatibility alias
+    - `openai/gpt-5.4` = current direct OpenAI API-key route in PI
+    - `openai/gpt-5.5` = future direct API-key route once OpenAI enables GPT-5.5 on the API
+    - `openai-codex/gpt-5.5` = Codex OAuth route in PI
+    - `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` = native Codex app-server route
     - `openai-codex:...` = auth profile id, not a model ref
 
     If you want the direct OpenAI Platform billing/limit path, set
     `OPENAI_API_KEY`. If you want ChatGPT/Codex subscription auth, sign in with
-    `openclaw models auth login --provider openai-codex` and keep model refs on
-    `openai/*` in new configs.
+    `openclaw models auth login --provider openai-codex` and use
+    `openai-codex/*` model refs for PI runs.
 
   </Accordion>
 
@@ -2218,7 +2227,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
     agents.defaults.model.primary
     ```
 
-    Models are referenced as `provider/model` (example: `openai/gpt-5.5`). If you omit the provider, OpenClaw first tries an alias, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider as a deprecated compatibility path. If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default. You should still **explicitly** set `provider/model`.
+    Models are referenced as `provider/model` (example: `openai/gpt-5.4` or `openai-codex/gpt-5.5`). If you omit the provider, OpenClaw first tries an alias, then a unique configured-provider match for that exact model id, and only then falls back to the configured default provider as a deprecated compatibility path. If that provider no longer exposes the configured default model, OpenClaw falls back to the first configured provider/model instead of surfacing a stale removed-provider default. You should still **explicitly** set `provider/model`.
 
   </Accordion>
 
@@ -2343,10 +2352,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   <Accordion title="Can I use GPT 5.5 for daily tasks and Codex 5.5 for coding?">
     Yes. Set one as default and switch as needed:
 
-    - **Quick switch (per session):** `/model gpt-5.5` for daily tasks, or keep the same model and switch auth/profile as needed.
-    - **Default:** set `agents.defaults.model.primary` to `openai/gpt-5.5`.
+    - **Quick switch (per session):** `/model openai/gpt-5.4` for current direct OpenAI API-key tasks or `/model openai-codex/gpt-5.5` for GPT-5.5 Codex OAuth tasks.
+    - **Default:** set `agents.defaults.model.primary` to `openai/gpt-5.4` for API-key usage or `openai-codex/gpt-5.5` for GPT-5.5 Codex OAuth usage.
     - **Sub-agents:** route coding tasks to sub-agents with a different default model.
 
+    Direct API-key access for `openai/gpt-5.5` is supported once OpenAI enables
+    GPT-5.5 on the public API. Until then GPT-5.5 is subscription/OAuth-only.
+
     See [Models](/concepts/models) and [Slash commands](/tools/slash-commands).
 
   </Accordion>
@@ -2354,9 +2366,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   <Accordion title="How do I configure fast mode for GPT 5.5?">
     Use either a session toggle or a config default:
 
-    - **Per session:** send `/fast on` while the session is using `openai/gpt-5.5`.
-    - **Per model default:** set `agents.defaults.models["openai/gpt-5.5"].params.fastMode` to `true`.
-    - **Legacy aliases:** older `openai-codex/gpt-*` entries can keep their own params, but new configs should put params on `openai/gpt-*`.
+    - **Per session:** send `/fast on` while the session is using `openai/gpt-5.4` or `openai-codex/gpt-5.5`.
+    - **Per model default:** set `agents.defaults.models["openai/gpt-5.4"].params.fastMode` or `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` to `true`.
 
     Example:
 
@@ -2365,7 +2376,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
       agents: {
         defaults: {
           models: {
-            "openai/gpt-5.5": {
+            "openai/gpt-5.4": {
               params: {
                 fastMode: true,
               },
@@ -2436,7 +2447,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
           model: { primary: "minimax/MiniMax-M2.7" },
           models: {
             "minimax/MiniMax-M2.7": { alias: "minimax" },
-            "openai/gpt-5.5": { alias: "gpt" },
+            "openai/gpt-5.4": { alias: "gpt" },
           },
         },
       },
@@ -2464,7 +2475,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
 
     - `opus` → `anthropic/claude-opus-4-6`
     - `sonnet` → `anthropic/claude-sonnet-4-6`
-    - `gpt` → `openai/gpt-5.5`
+    - `gpt` → `openai/gpt-5.4` for API-key setups, or `openai-codex/gpt-5.5` when configured for Codex OAuth
     - `gpt-mini` → `openai/gpt-5.4-mini`
     - `gpt-nano` → `openai/gpt-5.4-nano`
     - `gemini` → `google/gemini-3.1-pro-preview`

docs/help/testing.md

@@ -315,7 +315,7 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
   - No real keys required
   - Should be fast and stable
     <AccordionGroup>
-    <Accordion title="Projects, shards, and scoped lanes"> - Untargeted `pnpm test` runs twelve smaller shard configs (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) instead of one giant native root-project process. This cuts peak RSS on loaded machines and avoids auto-reply/extension work starving unrelated suites. - `pnpm test --watch` still uses the native root `vitest.config.ts` project graph, because a multi-shard watch loop is not practical. - `pnpm test`, `pnpm test:watch`, and `pnpm test:perf:imports` route explicit file/directory targets through scoped lanes first, so `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` avoids paying the full root project startup tax. - `pnpm test:changed` expands changed git paths into the same scoped lanes when the diff only touches routable source/test files; config/setup edits still fall back to the broad root-project rerun. - `pnpm check:changed` is the normal smart local gate for narrow work. It classifies the diff into core, core tests, extensions, extension tests, apps, docs, release metadata, and tooling, then runs the matching typecheck/lint/test lanes. Public Plugin SDK and plugin-contract changes include extension validation because extensions depend on those core contracts. Release metadata-only version bumps run targeted version/config/root-dependency checks instead of the full suite, with a guard that rejects package changes outside the top-level version field. - Import-light unit tests from agents, commands, plugins, auto-reply helpers, `plugin-sdk`, and similar pure utility areas route through the `unit-fast` lane, which skips `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files stay on the existing lanes. - Selected `plugin-sdk` and `commands` helper source files also map changed-mode runs to explicit sibling tests in those light lanes, so helper edits avoid rerunning the full heavy suite for that directory. - `auto-reply` has three dedicated buckets: top-level core helpers, top-level `reply.*` integration tests, and the `src/auto-reply/reply/**` subtree. This keeps the heaviest reply harness work off the cheap status/chunk/token tests.
+    <Accordion title="Projects, shards, and scoped lanes"> - Untargeted `pnpm test` runs twelve smaller shard configs (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) instead of one giant native root-project process. This cuts peak RSS on loaded machines and avoids auto-reply/extension work starving unrelated suites. - `pnpm test --watch` still uses the native root `vitest.config.ts` project graph, because a multi-shard watch loop is not practical. - `pnpm test`, `pnpm test:watch`, and `pnpm test:perf:imports` route explicit file/directory targets through scoped lanes first, so `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` avoids paying the full root project startup tax. - `pnpm test:changed` expands changed git paths into the same scoped lanes when the diff only touches routable source/test files; config/setup edits still fall back to the broad root-project rerun. - `pnpm check:changed` is the normal smart local gate for narrow work. It classifies the diff into core, core tests, extensions, extension tests, apps, docs, release metadata, and tooling, then runs the matching typecheck/lint/test lanes. Public Plugin SDK and plugin-contract changes include one extension validation pass because extensions depend on those core contracts. Release metadata-only version bumps run targeted version/config/root-dependency checks instead of the full suite, with a guard that rejects package changes outside the top-level version field. - Import-light unit tests from agents, commands, plugins, auto-reply helpers, `plugin-sdk`, and similar pure utility areas route through the `unit-fast` lane, which skips `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files stay on the existing lanes. - Selected `plugin-sdk` and `commands` helper source files also map changed-mode runs to explicit sibling tests in those light lanes, so helper edits avoid rerunning the full heavy suite for that directory. - `auto-reply` has three dedicated buckets: top-level core helpers, top-level `reply.*` integration tests, and the `src/auto-reply/reply/**` subtree. This keeps the heaviest reply harness work off the cheap status/chunk/token tests.
     </Accordion>
 
       <Accordion title="Embedded runner coverage">
@@ -348,17 +348,11 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
 
       <Accordion title="Fast local iteration">
         - `pnpm changed:lanes` shows which architectural lanes a diff triggers.
-        - The pre-commit hook runs `pnpm check:changed --staged` after staged
-          formatting/linting, so core-only commits do not pay extension test cost
-          unless they touch public extension-facing contracts. Release
-          metadata-only commits stay on the targeted
-          version/config/root-dependency lane.
-        - If the exact staged change set was already validated with
-          equal-or-stronger gates, use
-          `scripts/committer --fast "<message>" <files...>` to skip only the
-          changed-scope hook rerun. Staged format/lint still run. Mention the
-          completed gates in your handoff. This is also acceptable after an
-          isolated flaky hook failure is rerun and passes with scoped proof.
+        - The pre-commit hook is formatting-only. It restages formatted files and
+          does not run lint, typecheck, or tests.
+        - Run `pnpm check:changed` explicitly before handoff or push when you
+          need the smart local gate. Public Plugin SDK and plugin-contract
+          changes include one extension validation pass.
         - `pnpm test:changed` routes through scoped lanes when the changed paths
           map cleanly to a smaller suite.
         - `pnpm test:max` and `pnpm test:changed:max` keep the same routing
@@ -379,6 +373,10 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
           import-breakdown output.
         - `pnpm test:perf:imports:changed` scopes the same profiling view to
           files changed since `origin/main`.
+        - When one hot test still spends most of its time in startup imports,
+          keep heavy dependencies behind a narrow local `*.runtime.ts` seam and
+          mock that seam directly instead of deep-importing runtime helpers just
+          to pass them through `vi.mock(...)`.
         - `pnpm test:perf:changed:bench -- --ref <git-ref>` compares routed
           `test:changed` against the native root-project path for that committed
           diff and prints wall time plus macOS max RSS.
@@ -512,7 +510,7 @@ Live tests are split into two layers so we can isolate failures:
 - How to select models:
   - `OPENCLAW_LIVE_MODELS=modern` to run the modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
   - `OPENCLAW_LIVE_MODELS=all` is an alias for the modern allowlist
-  - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,..."` (comma allowlist)
+  - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (comma allowlist)
   - Modern/all sweeps default to a curated high-signal cap; set `OPENCLAW_LIVE_MAX_MODELS=0` for an exhaustive modern sweep or a positive number for a smaller cap.
 - How to select providers:
   - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist)
@@ -698,8 +696,9 @@ Docker notes:
 - Optional Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
 - The smoke sets `OPENCLAW_AGENT_HARNESS_FALLBACK=none` so a broken Codex
   harness cannot pass by silently falling back to PI.
-- Auth: `OPENAI_API_KEY` from the shell/profile, plus optional copied
-  `~/.codex/auth.json` and `~/.codex/config.toml`
+- Auth: Codex app-server auth from the local Codex subscription login. Docker
+  smokes can also provide `OPENAI_API_KEY` for non-Codex probes when applicable,
+  plus optional copied `~/.codex/auth.json` and `~/.codex/config.toml`.
 
 Local recipe:
 
@@ -740,13 +739,13 @@ Docker notes:
 Narrow, explicit allowlists are fastest and least flaky:
 
 - Single model, direct (no gateway):
-  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
 
 - Single model, gateway smoke:
-  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 - Tool calling across several providers:
-  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 - Google focus (Gemini API key + Antigravity):
   - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
@@ -769,8 +768,8 @@ There is no fixed “CI model list” (live is opt-in), but these are the **reco
 
 This is the “common models” run we expect to keep working:
 
-- OpenAI (non-Codex): `openai/gpt-5.5` (optional: `openai/gpt-5.4-mini`)
-- OpenAI Codex OAuth: `openai/gpt-5.5` (`openai-codex/gpt-*` remains a legacy alias)
+- OpenAI (non-Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`)
+- OpenAI Codex OAuth: `openai-codex/gpt-5.5`
 - Anthropic: `anthropic/claude-opus-4-6` (or `anthropic/claude-sonnet-4-6`)
 - Google (Gemini API): `google/gemini-3.1-pro-preview` and `google/gemini-3-flash-preview` (avoid older Gemini 2.x models)
 - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` and `google-antigravity/gemini-3-flash`
@@ -778,13 +777,13 @@ This is the “common models” run we expect to keep working:
 - MiniMax: `minimax/MiniMax-M2.7`
 
 Run gateway smoke with tools + image:
-`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 ### Baseline: tool calling (Read + optional Exec)
 
 Pick at least one per provider family:
 
-- OpenAI: `openai/gpt-5.5` (or `openai/gpt-5.4-mini`)
+- OpenAI: `openai/gpt-5.4` (or `openai/gpt-5.4-mini`)
 - Anthropic: `anthropic/claude-opus-4-6` (or `anthropic/claude-sonnet-4-6`)
 - Google: `google/gemini-3-flash-preview` (or `google/gemini-3.1-pro-preview`)
 - Z.AI (GLM): `zai/glm-4.7`
@@ -869,12 +868,13 @@ If you want to rely on env keys (e.g. exported in your `~/.profile`), run local
   - `google`
   - `minimax`
   - `openai`
+  - `openrouter`
   - `vydra`
   - `xai`
 - Optional narrowing:
-  - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"`
-  - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
-  - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"`
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"`
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
+  - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
 - Optional auth behavior:
   - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` to force profile-store auth and ignore env-only overrides
 

docs/install/docker.md

@@ -6,8 +6,6 @@ read_when:
 title: "Docker"
 ---
 
-# Docker (optional)
-
 Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.
 
 ## Is Docker right for me?

docs/install/fly.md

@@ -156,7 +156,7 @@ read_when:
         "defaults": {
           "model": {
             "primary": "anthropic/claude-opus-4-6",
-            "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.5"]
+            "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"]
           },
           "maxConcurrent": 4
         },

docs/nodes/audio.md

@@ -189,3 +189,9 @@ When `requireMention: true` is set for a group chat, OpenClaw now transcribes au
 - For `parakeet-mlx`, if you pass `--output-dir`, OpenClaw reads `<output-dir>/<media-basename>.txt` when `--output-format` is `txt` (or omitted); non-`txt` output formats fall back to stdout parsing.
 - Keep timeouts reasonable (`timeoutSeconds`, default 60s) to avoid blocking the reply queue.
 - Preflight transcription only processes the **first** audio attachment for mention detection. Additional audio is processed during the main media understanding phase.
+
+## Related
+
+- [Media understanding](/nodes/media-understanding)
+- [Talk mode](/nodes/talk)
+- [Voice wake](/nodes/voicewake)

docs/nodes/camera.md

@@ -6,8 +6,6 @@ read_when:
 title: "Camera capture"
 ---
 
-# Camera capture (agent)
-
 OpenClaw supports **camera capture** for agent workflows:
 
 - **iOS node** (paired via Gateway): capture a **photo** (`jpg`) or **short video clip** (`mp4`, with optional audio) via `node.invoke`.
@@ -160,3 +158,9 @@ openclaw nodes screen record --node <id> --duration 10s --fps 15   # prints MEDI
 Notes:
 
 - Requires macOS **Screen Recording** permission (TCC).
+
+## Related
+
+- [Image and media support](/nodes/images)
+- [Media understanding](/nodes/media-understanding)
+- [Location command](/nodes/location-command)

docs/nodes/images.md

@@ -71,3 +71,9 @@ The WhatsApp channel runs via **Baileys Web**. This document captures the curren
 - Cover send + reply flows for image/audio/document cases.
 - Validate recompression for images (size bound) and voice-note flag for audio.
 - Ensure multi-media replies fan out as sequential sends.
+
+## Related
+
+- [Camera capture](/nodes/camera)
+- [Media understanding](/nodes/media-understanding)
+- [Audio and voice notes](/nodes/audio)

docs/nodes/location-command.md

@@ -6,8 +6,6 @@ read_when:
 title: "Location command"
 ---
 
-# Location command (nodes)
-
 ## TL;DR
 
 - `location.get` is a node command (via `node.invoke`).
@@ -96,3 +94,9 @@ Errors (stable codes):
 - Off: “Location sharing is disabled.”
 - While Using: “Only when OpenClaw is open.”
 - Precise: “Use precise GPS location. Toggle off to share approximate location.”
+
+## Related
+
+- [Channel location parsing](/channels/location)
+- [Camera capture](/nodes/camera)
+- [Talk mode](/nodes/talk)

docs/nodes/media-understanding.md

@@ -222,11 +222,11 @@ If you omit `capabilities`, the entry is eligible for the list it appears in.
 
 ## Provider support matrix (OpenClaw integrations)
 
-| Capability | Provider integration                                                                   | Notes                                                                                                                                    |
-| ---------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Image      | OpenAI, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Vendor plugins register image support; MiniMax and MiniMax OAuth both use `MiniMax-VL-01`; image-capable config providers auto-register. |
-| Audio      | OpenAI, Groq, Deepgram, Google, Mistral                                                | Provider transcription (Whisper/Deepgram/Gemini/Voxtral).                                                                                |
-| Video      | Google, Qwen, Moonshot                                                                 | Provider video understanding via vendor plugins; Qwen video understanding uses the Standard DashScope endpoints.                         |
+| Capability | Provider integration                                                                                                         | Notes                                                                                                                                                                                                                                   |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Image      | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Vendor plugins register image support; `openai-codex/*` uses OAuth provider plumbing; `codex/*` uses a bounded Codex app-server turn; MiniMax and MiniMax OAuth both use `MiniMax-VL-01`; image-capable config providers auto-register. |
+| Audio      | OpenAI, Groq, Deepgram, Google, Mistral                                                                                      | Provider transcription (Whisper/Deepgram/Gemini/Voxtral).                                                                                                                                                                               |
+| Video      | Google, Qwen, Moonshot                                                                                                       | Provider video understanding via vendor plugins; Qwen video understanding uses the Standard DashScope endpoints.                                                                                                                        |
 
 MiniMax note:
 
@@ -422,7 +422,7 @@ File-attachment extraction behavior:
 When media understanding runs, `/status` includes a short summary line:
 
 ```
-📎 Media: image ok (openai/gpt-5.5) · audio skipped (maxBytes)
+📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)
 ```
 
 This shows per‑capability outcomes and the chosen provider/model when applicable.

docs/nodes/talk.md

@@ -88,3 +88,9 @@ Defaults:
 - `stability` for `eleven_v3` is validated to `0.0`, `0.5`, or `1.0`; other models accept `0..1`.
 - `latency_tier` is validated to `0..4` when set.
 - Android supports `pcm_16000`, `pcm_22050`, `pcm_24000`, and `pcm_44100` output formats for low-latency AudioTrack streaming.
+
+## Related
+
+- [Voice wake](/nodes/voicewake)
+- [Audio and voice notes](/nodes/audio)
+- [Media understanding](/nodes/media-understanding)

docs/nodes/troubleshooting.md

@@ -119,3 +119,9 @@ Related:
 - [/nodes/location-command](/nodes/location-command)
 - [/tools/exec-approvals](/tools/exec-approvals)
 - [/gateway/pairing](/gateway/pairing)
+
+## Related
+
+- [Nodes overview](/nodes)
+- [Gateway troubleshooting](/gateway/troubleshooting)
+- [Channel troubleshooting](/channels/troubleshooting)

docs/nodes/voicewake.md

@@ -6,8 +6,6 @@ read_when:
 title: "Voice wake"
 ---
 
-# Voice Wake (Global Wake Words)
-
 OpenClaw treats **wake words as a single global list** owned by the **Gateway**.
 
 - There are **no per-node custom wake words**.
@@ -64,3 +62,9 @@ Who receives it:
 
 - Voice Wake is currently disabled in Android runtime/Settings.
 - Android voice uses manual mic capture in the Voice tab instead of wake-word triggers.
+
+## Related
+
+- [Talk mode](/nodes/talk)
+- [Audio and voice notes](/nodes/audio)
+- [Media understanding](/nodes/media-understanding)

docs/platforms/android.md

@@ -7,8 +7,6 @@ read_when:
 title: "Android app"
 ---
 
-# Android App (Node)
-
 > **Note:** The Android app has not been publicly released yet. The source code is available in the [OpenClaw repository](https://github.com/openclaw/openclaw) under `apps/android`. You can build it yourself using Java 17 and the Android SDK (`./gradlew :app:assemblePlayDebug`). See [apps/android/README.md](https://github.com/openclaw/openclaw/blob/main/apps/android/README.md) for build instructions.
 
 ## Support snapshot

docs/platforms/ios.md

@@ -7,8 +7,6 @@ read_when:
 title: "iOS app"
 ---
 
-# iOS App (Node)
-
 Availability: internal preview. The iOS app is not publicly distributed yet.
 
 ## What it does

docs/platforms/mac/bundled-gateway.md

@@ -7,8 +7,6 @@ read_when:
 title: "Gateway on macOS"
 ---
 
-# Gateway on macOS (external launchd)
-
 OpenClaw.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
 expects an **external** `openclaw` CLI install, does not spawn the Gateway as a
 child process, and manages a per‑user launchd service to keep the Gateway

docs/platforms/mac/canvas.md

@@ -7,8 +7,6 @@ read_when:
 title: "Canvas"
 ---
 
-# Canvas (macOS app)
-
 The macOS app embeds an agent‑controlled **Canvas panel** using `WKWebView`. It
 is a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive
 UI surfaces.

docs/platforms/mac/peekaboo.md

@@ -7,8 +7,6 @@ read_when:
 title: "Peekaboo bridge"
 ---
 
-# Peekaboo Bridge (macOS UI automation)
-
 OpenClaw can host **PeekabooBridge** as a local, permission‑aware UI automation
 broker. This lets the `peekaboo` CLI drive UI automation while reusing the
 macOS app’s TCC permissions.

docs/platforms/mac/permissions.md

@@ -7,8 +7,6 @@ read_when:
 title: "macOS permissions"
 ---
 
-# macOS permissions (TCC)
-
 macOS permission grants are fragile. TCC associates a permission grant with the
 app's code signature, bundle identifier, and on-disk path. If any of those change,
 macOS treats the app as new and may drop or hide prompts.

docs/plugins/agent-tools.md

@@ -8,3 +8,8 @@ title: "Registering tools"
 # Registering Tools in Plugins
 
 This page has moved. See [Building Plugins: Registering agent tools](/plugins/building-plugins#registering-agent-tools).
+
+## Related
+
+- [Building plugins](/plugins/building-plugins)
+- [Plugin SDK setup](/plugins/sdk-setup)

docs/plugins/architecture.md

@@ -1517,3 +1517,9 @@ That keeps the rule simple:
 - vendor plugins own vendor implementations
 - feature/channel plugins consume runtime helpers
 - contract tests keep ownership explicit
+
+## Related
+
+- [Building plugins](/plugins/building-plugins)
+- [Plugin SDK setup](/plugins/sdk-setup)
+- [Plugin manifest](/plugins/manifest)