docs(changelog): reference codex doctor repair

Fixes #70688.
Co-authored-by: Jon Brown <801241+jb510@users.noreply.github.com>

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

@@ -49,6 +49,66 @@ pnpm openclaw qa suite \
 5. If the user wants to watch the live UI, find the current `openclaw-qa` listen port and report `http://127.0.0.1:<port>`.
 6. If a scenario fails, fix the product or harness root cause, then rerun the full lane.
 
+## QA credentials and 1Password
+
+- Use `op` only inside `tmux` for QA secret lookup in this repo.
+- Quick auth check inside tmux:
+
+```bash
+op account list
+```
+
+- Direct Telegram npm live test secrets currently live in 1Password item:
+  - vault: `OpenClaw`
+  - item: `Telegram E2E`
+- That item is the first place to look for:
+  - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
+  - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
+  - `OPENCLAW_QA_PROVIDER_MODE`
+  - `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC`
+- Convex QA secrets currently live in 1Password items:
+  - vault: `OpenClaw`
+  - item: `OPENCLAW_QA_CONVEX_SITE_URL`
+  - item: `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
+  - item: `OPENCLAW_QA_CONVEX_SECRET_CI`
+- Additional related notes/login items seen during QA credential work:
+  - vault: `Private`
+  - items: `OPENCLAW QA`, `Convex`, `Telegram`
+- If a required value is missing from those notes:
+  - do not guess
+  - ask the maintainer/operator for the current value or the current 1Password item name
+  - for Telegram direct runs, `OPENCLAW_QA_TELEGRAM_GROUP_ID` may be stored separately from `Telegram E2E`
+  - for Convex runs, the leased Telegram credential should provide the Telegram group id and bot tokens together; do not require a separate `OPENCLAW_QA_TELEGRAM_GROUP_ID`
+  - for Convex runs, prefer `OpenClaw/OPENCLAW_QA_CONVEX_SITE_URL`; if that is stale or unclear, ask for the active pool URL before running
+- Prefer direct Telegram envs for the npm Telegram Docker lane when available:
+
+```bash
+OPENCLAW_QA_TELEGRAM_GROUP_ID="..." \
+OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN="..." \
+OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN="..." \
+OPENCLAW_QA_PROVIDER_MODE="mock-openai" \
+OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC="openclaw@beta" \
+pnpm test:docker:npm-telegram-live
+```
+
+- Prefer Convex mode when the goal is stable shared QA infra:
+  - round-robin credential leasing
+  - thinner wrapper for channel-specific setup
+  - CLI/admin flows around the pooled credentials
+- Live npm Telegram Docker lane note:
+  - `scripts/e2e/npm-telegram-live-runner.ts` reads `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE`
+  - do not assume `OPENCLAW_QA_PROVIDER_MODE` is consumed by that wrapper
+  - if a 1Password note only gives `OPENCLAW_QA_PROVIDER_MODE`, map it explicitly to `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE` before running the Docker lane
+- Verified live shape:
+  - Convex mode can pass the real Docker lane without direct Telegram env vars
+  - leased Telegram payload includes the group id coupled to the driver/SUT tokens
+  - a real run of `pnpm test:docker:npm-telegram-live` passed with:
+    - `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`
+    - `OPENCLAW_QA_CREDENTIAL_ROLE=maintainer`
+    - `OPENCLAW_QA_CONVEX_SITE_URL`
+    - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`
+    - `OPENCLAW_NPM_TELEGRAM_PROVIDER_MODE=mock-openai`
+
 ## Character evals
 
 Use `qa character-eval` for style/persona/vibe checks across multiple live models.

.github/workflows/install-smoke.yml

@@ -1,10 +1,6 @@
 name: Install Smoke
 
 on:
-  push:
-    branches: [main]
-  pull_request:
-    types: [opened, reopened, synchronize, ready_for_review, converted_to_draft]
   schedule:
     - cron: "17 3 * * *"
   workflow_dispatch:
@@ -30,7 +26,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.event_name == 'workflow_dispatch' && format('{0}-manual-{1}', github.workflow, github.run_id) || github.event_name == 'pull_request' && format('{0}-{1}', github.workflow, github.event.pull_request.number) || format('{0}-{1}', github.workflow, github.ref) }}
+  group: ${{ github.event_name == 'workflow_dispatch' && format('{0}-manual-{1}', github.workflow, github.run_id) || format('{0}-{1}', github.workflow, github.ref) }}
   cancel-in-progress: true
 
 env:
@@ -38,7 +34,6 @@ env:
 
 jobs:
   preflight:
-    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
     runs-on: ubuntu-24.04
     outputs:
       docs_only: ${{ steps.manifest.outputs.docs_only }}
@@ -56,67 +51,19 @@ jobs:
           persist-credentials: false
           submodules: false
 
-      - name: Ensure preflight base commit
-        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 }}
-          fetch-ref: ${{ github.event_name == 'push' && github.ref_name || github.event.pull_request.base.ref }}
-
-      - name: Detect docs-only changes
-        id: docs_scope
-        uses: ./.github/actions/detect-docs-changes
-
-      - name: Detect changed smoke scope
-        id: changed_scope
-        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
-
-          if [ "${{ github.event_name }}" = "push" ]; then
-            BASE="${{ github.event.before }}"
-          else
-            BASE="${{ github.event.pull_request.base.sha }}"
-          fi
-
-          node scripts/ci-changed-scope.mjs --base "$BASE" --head HEAD
-
       - name: Build install-smoke CI manifest
         id: manifest
         env:
-          OPENCLAW_CI_DOCS_ONLY: ${{ steps.docs_scope.outputs.docs_only }}
           OPENCLAW_CI_EVENT_NAME: ${{ github.event_name }}
-          OPENCLAW_CI_FORCE_FULL_INSTALL_SMOKE: ${{ (github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || github.event_name == 'workflow_call') && 'true' || 'false' }}
           OPENCLAW_CI_WORKFLOW_BUN_GLOBAL_INSTALL_SMOKE: ${{ inputs.run_bun_global_install_smoke || 'false' }}
-          OPENCLAW_CI_RUN_FAST_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_fast_install_smoke || steps.changed_scope.outputs.run_changed_smoke || 'false' }}
-          OPENCLAW_CI_RUN_FULL_INSTALL_SMOKE: ${{ steps.changed_scope.outputs.run_full_install_smoke || 'false' }}
         run: |
-          docs_only="${OPENCLAW_CI_DOCS_ONLY:-false}"
           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
+          docs_only=false
+          run_fast_install_smoke=true
+          run_full_install_smoke=true
           run_bun_global_install_smoke=false
-          run_install_smoke=false
-          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" ] && [ "$event_name" != "push" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_full_install_smoke=true
-            run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$run_changed_full_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_install_smoke=true
-          elif [ "$docs_only" != "true" ] && [ "$run_changed_fast_install_smoke" = "true" ]; then
-            run_fast_install_smoke=true
-            run_install_smoke=true
-          fi
+          run_install_smoke=true
           if [ "$event_name" = "schedule" ]; then
             run_bun_global_install_smoke=true
           elif [ "$event_name" = "workflow_dispatch" ] || [ "$event_name" = "workflow_call" ]; then
@@ -326,7 +273,6 @@ jobs:
           provenance: false
 
       - name: Build installer non-root image
-        if: github.event_name != 'pull_request'
         uses: useblacksmith/build-push-action@cbd1f60d194a98cb3be5523b15134501eaf0fbf3 # v2
         with:
           context: ./scripts/docker
@@ -356,8 +302,8 @@ jobs:
           OPENCLAW_NO_ONBOARD: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_CLI: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_IMAGE_BUILD: "1"
-          OPENCLAW_INSTALL_NONROOT_SKIP_IMAGE_BUILD: ${{ github.event_name == 'pull_request' && '0' || '1' }}
-          OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT: ${{ github.event_name == 'pull_request' && '1' || '0' }}
+          OPENCLAW_INSTALL_NONROOT_SKIP_IMAGE_BUILD: "1"
+          OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT: "0"
           OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL: "1"
           OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS: "1"
           OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE: latest

CHANGELOG.md

@@ -6,16 +6,20 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Diagnostics/OTEL: add a lightweight diagnostic trace-context carrier for future span correlation without adding OTEL SDK state to core. Thanks @vincentkoc.
 - Control UI/chat: add a Steer action on queued messages so a browser follow-up can be injected into the active run without retyping it.
 - Control UI/Talk: add browser WebRTC realtime voice sessions backed by OpenAI Realtime, with Gateway-minted ephemeral client secrets and `openclaw_agent_consult` handoff to the full OpenClaw agent.
 - Agents/tools: add optional per-call `timeoutMs` support for image, video, music, and TTS generation tools so agents can extend provider request timeouts only when a specific generation needs it.
 - Agents/subagents: add optional forked context for native `sessions_spawn` runs so agents can let a child inherit the requester transcript when needed, while keeping clean isolated sessions as the default; includes prompt guidance, context-engine hook metadata, docs, and QA coverage.
 - Codex harness: add structured debug logging for embedded harness selection decisions so `/status` stays simple while gateway logs explain auto-selection and Pi fallback reasons. (#70760) Thanks @100yenadmin.
 - Dependencies/Pi: update bundled Pi packages to `0.70.0`, use Pi's upstream `gpt-5.5` catalog metadata for OpenAI and OpenAI Codex, and keep only local `gpt-5.5-pro` forward-compat handling.
+- Models/CLI: speed up `openclaw models list --all --provider <id>` for bundled providers with safe static catalogs while keeping live and third-party providers on registry discovery. (#70632) Thanks @shakkernerd.
 - Models/CLI: avoid broad registry enumeration for default `openclaw models list`, reducing default listing latency while preserving configured-row output. (#70883) Thanks @shakkernerd.
 - Models/CLI: split `openclaw models list` row-source orchestration and registry loading into narrower helpers without changing list output behavior. (#70867) Thanks @shakkernerd.
+- Codex harness/context-engine: run context-engine bootstrap, assembly, post-turn maintenance, and engine-owned compaction in Codex app-server sessions while keeping native Codex thread state and compaction auditable. (#70809) Thanks @jalehman.
 - Plugins/Google Meet: add a bundled participant plugin with personal Google auth, explicit meeting URL joins, Chrome and Twilio transports, and realtime voice support. (#70765) Thanks @steipete.
 - Plugins/Google Meet: default Chrome realtime sessions to OpenAI plus SoX `rec`/`play` audio bridge commands, so the usual setup only needs the plugin enabled and `OPENAI_API_KEY`.
+- Plugins/Google Meet: add a `chrome-node` transport so a paired macOS node, such as a Parallels VM, can own Chrome, BlackHole, and SoX while the Gateway machine keeps the agent and model key.
 - Providers/OpenAI: add image generation and reference-image editing through Codex OAuth, so `openai/gpt-image-2` works without an `OPENAI_API_KEY`. Fixes #70703.
 - Providers/OpenRouter: add image generation and reference-image editing through `image_generate`, so OpenRouter image models work with `OPENROUTER_API_KEY`. Fixes #55066 via #67668. Thanks @notamicrodose.
 - Image generation: let agents request provider-supported quality and output format hints, and pass OpenAI-specific background, moderation, compression, and user hints through the `image_generate` tool. (#70503) Thanks @ottodeng.
@@ -23,9 +27,17 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Codex harness: route native `request_user_input` prompts back to the originating chat, preserve queued follow-up answers, and honor newer app-server command approval amendment decisions.
+- Codex status: report Codex CLI OAuth as `oauth (codex-cli)` for native `codex/*` sessions instead of showing unknown auth. Fixes #70688. Thanks @jb510.
+- Codex harness/context-engine: redact context-engine assembly failures before logging, so fallback warnings do not serialize raw error objects. (#70809) Thanks @jalehman.
+- WhatsApp/onboarding: keep first-run setup entry loading off the Baileys runtime dependency path, so packaged QuickStart installs can show WhatsApp setup before runtime deps are staged. Fixes #70932.
+- Block streaming: suppress final assembled text after partial block-delivery aborts when the already-sent text chunks exactly cover the final reply, preventing duplicate replies without dropping unrelated short messages. Fixes #70921.
+- Codex harness/Windows: resolve npm-installed `codex.cmd` shims through PATHEXT before starting the native app-server, so `codex/*` models work without a manual `.exe` shim. Fixes #70913.
+- Slack/groups: classify MPIM group DMs as group chat context and suppress verbose tool/plan progress on Slack non-DM surfaces, so internal "Working…" traces no longer leak into rooms. Fixes #70912.
 - Agents/replay: stop OpenAI/Codex transcript replay from synthesizing missing tool results while still preserving synthetic repair on Anthropic, Gemini, and Bedrock transport-owned sessions. (#61556) Thanks @VictorJeon and @vincentkoc.
 - Telegram/media replies: parse remote markdown image syntax into outbound media payloads on the final reply path, so Telegram group chats stop falling back to plain-text image URLs when the model or a tool emits `![...](...)` instead of a `MEDIA:` token. (#66191) Thanks @apezam and @vincentkoc.
 - Agents/WebChat: surface non-retryable provider failures such as billing, auth, and rate-limit errors from the embedded runner instead of logging `surface_error` and leaving webchat with no rendered error. Fixes #70124. (#70848) Thanks @truffle-dev.
+- WhatsApp: unify outbound media normalization across direct sends and auto-replies. Thanks @mcaxtr.
 - Memory/CLI: declare the built-in `local` embedding provider in the memory-core manifest, so standalone `openclaw memory status`, `index`, and `search` can resolve local embeddings just like the gateway runtime. Fixes #70836. (#70873) Thanks @mattznojassist.
 - Gateway/WebChat: preserve image attachments for text-only primary models by offloading them as media refs instead of dropping them, so configured image tools can still inspect the original file. Fixes #68513, #44276, #51656, #70212.
 - Plugins/Google Meet: hang up delegated Twilio calls on leave, clean up Chrome realtime audio bridges when launch fails, and use a flat provider-safe tool schema.
@@ -34,6 +46,7 @@ Docs: https://docs.openclaw.ai
 - 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: propagate configured attempt timeouts into guarded per-request dispatchers, so slow local LLM calls such as Ollama no longer fail at Undici's default 60-second body timeout. Fixes #70829. (#70831) Thanks @DranboFieldston.
 - Agents/transport: stop embedded runs from lowering the process-wide undici stream timeouts, so slow Gemini image generation and other long-running provider requests no longer inherit short run-attempt headers timeouts. Fixes #70423. Thanks @giangthb.
 - Providers/OpenRouter: send image-understanding prompts as user text before image parts, restoring non-empty vision responses for OpenRouter multimodal models. Fixes #70410.
 - Plugins/providers: mirror runtime auth choices in bundled provider manifests and detect `KIMI_API_KEY` for Moonshot/Kimi web search before plugin runtime loads. Thanks @vincentkoc.
@@ -46,6 +59,7 @@ Docs: https://docs.openclaw.ai
 - Plugins/QR: replace legacy `qrcode-terminal` QR rendering with bounded `qrcode-tui` helpers for plugin login/setup flows. (#65969) Thanks @vincentkoc.
 - 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.
@@ -78,6 +92,9 @@ Docs: https://docs.openclaw.ai
 - 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.
+- Memory/dreaming: decouple the managed dreaming cron from heartbeat by running it as an isolated lightweight agent turn, so dreaming runs even when heartbeat is disabled for the default agent and is no longer skipped by `heartbeat.activeHours`. `openclaw doctor --fix` migrates stale main-session dreaming jobs in persisted cron configs to the new shape. Fixes #69811, #67397, #68972. (#70737) Thanks @jalehman.
+- Doctor/Codex: enable the bundled Codex plugin from `openclaw doctor --fix` when the OpenAI plugin is explicitly enabled but Codex is still off, restoring `codex/*` model availability after plugin config drift. (#70767) Thanks @ngutman.
+
 
 ## 2026.4.22
 
@@ -251,7 +268,6 @@ Docs: https://docs.openclaw.ai
 - CLI/channels: resolve channel presence through a shared policy that keeps ambient env vars and stale persisted auth from surfacing disabled bundled plugins in status, doctor, security audit, and cron delivery validation unless the channel or plugin is effectively enabled or explicitly configured. (#69862) Thanks @gumadeiras.
 - Doctor/plugins: hydrate legacy partial interactive handler state before plugin reload clears dedupe caches, so `openclaw doctor` and post-update doctor runs no longer crash with `Cannot read properties of undefined (reading 'clear')`. (#70135) Thanks @ngutman.
 - Control UI/config: preserve intentionally empty raw config snapshots when clearing pending updates so reset restores the original bytes instead of synthesizing JSON for blank config files. (#68178) Thanks @BunsDev.
-- memory-core/dreaming: surface a `Dreaming status: blocked` line in `openclaw memory status` when dreaming is enabled but the heartbeat that drives the managed cron is not firing for the default agent, and add a Troubleshooting section to the dreaming docs covering the two common causes (per-agent `heartbeat` blocks excluding `main`, and `heartbeat.every` set to `0`/empty/invalid), so the silent failure described in #69843 becomes legible on the status surface.
 - Cron/run-log: report generic `message` tool sends under the resolved delivery channel when they match the cron target, while preserving account-specific mismatch checks for delivery traces. (#69940) Thanks @davehappyminion.
 - Doctor/channels: merge configured-channel doctor hooks across read-only, loaded, setup, and runtime plugin discovery so partial adapters no longer hide runtime-only compatibility repair or allowlist warnings, preserve disabled-channel opt-outs, and ignore malformed hook values before they can mask valid fallbacks. (#69919) Thanks @gumadeiras.
 - Models/CLI: show bundled provider-owned static catalog rows in `models list --all` before auth is configured, including Kimi K2.6 rows for Moonshot, OpenRouter, and Vercel AI Gateway, while keeping local-only and workspace plugin catalog paths isolated. (#69909) Thanks @shakkernerd.

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2330,20 +2330,17 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
     public let provider: String?
     public let model: String?
     public let voice: String?
-    public let instructions: String?
 
     public init(
         sessionkey: String?,
         provider: String?,
         model: String?,
-        voice: String?,
-        instructions: String?)
+        voice: String?)
     {
         self.sessionkey = sessionkey
         self.provider = provider
         self.model = model
         self.voice = voice
-        self.instructions = instructions
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2351,7 +2348,6 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
         case provider
         case model
         case voice
-        case instructions
     }
 }
 

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

@@ -2330,20 +2330,17 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
     public let provider: String?
     public let model: String?
     public let voice: String?
-    public let instructions: String?
 
     public init(
         sessionkey: String?,
         provider: String?,
         model: String?,
-        voice: String?,
-        instructions: String?)
+        voice: String?)
     {
         self.sessionkey = sessionkey
         self.provider = provider
         self.model = model
         self.voice = voice
-        self.instructions = instructions
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -2351,7 +2348,6 @@ public struct TalkRealtimeSessionParams: Codable, Sendable {
         case provider
         case model
         case voice
-        case instructions
     }
 }
 

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-d3b5638e205a94e40d07aa1830c8d57135df18ff9388fb7d72ee84c791ac293f  config-baseline.json
+f0421335bfd388b7ebe1b8d478036ece4bf5eb8fd7b1de81b8cdc4ec6522ce20  config-baseline.json
 bf00f7910d8f0d8e12592e8a1c6bd0397f8e62fef2c11eb0cbd3b3a3e2a78ffe  config-baseline.core.json
 22d7cd6d8279146b2d79c9531a55b80b52a2c99c81338c508104729154fdd02d  config-baseline.channel.json
-a91304e3566ecc8906f199b88a2e38eaee86130aad799bf4d62921e2f0ddc1b5  config-baseline.plugin.json
+c6f99aed28b98e5914585956ec303b615a8ef975abf5cec186a61781c20b9106  config-baseline.plugin.json

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

@@ -1,2 +1,2 @@
-96905c33f4498446f612ae17dee6affdf84ef0e2e5a0f25bf7191c315f5b826f  plugin-sdk-api-baseline.json
-d8eb6331562fde29531eaac18409bb7fabcc70623bf25395f8e5710a49765f0f  plugin-sdk-api-baseline.jsonl
+3ce0dadfe0cac406051ff95ee8201a508d588e634b98ac22659e6b010c3641f6  plugin-sdk-api-baseline.json
+69c9058277b146196a3a3ef49fe193e42987a3642a233732370c9ddae60ddf62  plugin-sdk-api-baseline.jsonl

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

@@ -403,6 +403,10 @@
     "source": "Tencent Cloud (TokenHub)",
     "target": "腾讯云（TokenHub）"
   },
+  {
+    "source": "Codex Harness Context Engine Port",
+    "target": "Codex Harness Context Engine Port"
+  },
   {
     "source": "/gateway/configuration#strict-validation",
     "target": "/gateway/configuration#strict-validation"

docs/auth-credential-semantics.md

@@ -76,3 +76,8 @@ For script compatibility, probe errors keep this first line unchanged:
 `Auth profile credentials are missing or expired.`
 
 Human-friendly detail and stable reason codes may be added on subsequent lines.
+
+## Related
+
+- [Secrets management](/gateway/secrets)
+- [Auth storage](/concepts/oauth)

docs/brave-search.md

@@ -101,3 +101,7 @@ await web_search({
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
 
 See [Web tools](/tools/web) for the full web_search configuration.
+
+## Related
+
+- [Brave search](/tools/brave-search)

docs/channels/broadcast-groups.md

@@ -433,14 +433,10 @@ Planned features:
 - [ ] Dynamic agent selection (choose agents based on message content)
 - [ ] Agent priorities (some agents respond before others)
 
-## See Also
-
-- [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)
+- [Multi-agent sandbox tools](/tools/multi-agent-sandbox-tools)
+- [Session management](/concepts/session)

docs/channels/msteams.md

@@ -75,7 +75,7 @@ Disable with:
 
 - Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
 - `channels.msteams.allowFrom` should use stable AAD object IDs.
-- UPNs/display names are mutable; direct matching is disabled by default and only enabled with `channels.msteams.dangerouslyAllowNameMatching: true`.
+- Do not rely on UPN/display-name matching for allowlists — they can change. OpenClaw disables direct name matching by default; opt in explicitly with `channels.msteams.dangerouslyAllowNameMatching: true`.
 - The wizard can resolve names to IDs via Microsoft Graph when credentials allow.
 
 **Group access**

docs/channels/whatsapp.md

@@ -164,7 +164,7 @@ OpenClaw recommends running WhatsApp on a separate number when possible. (The ch
 
     - pairings are persisted in channel allow-store and merged with configured `allowFrom`
     - if no allowlist is configured, the linked self number is allowed by default
-    - outbound `fromMe` DMs are never auto-paired
+    - OpenClaw never auto-pairs outbound `fromMe` DMs (messages you send to yourself from the linked device)
 
   </Tab>
 

docs/ci.md

@@ -91,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 splits smoke coverage into `run_fast_install_smoke` and `run_full_install_smoke`. Pull requests run the fast path for Docker/package surfaces, bundled plugin package/manifest changes, and core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 120-second command timeout. The full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. `main` pushes, including merge commits, do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation. The slow Bun global install image-provider smoke is separately gated by `run_bun_global_install_smoke`; it runs on the nightly schedule and from the release checks workflow, and manual `install-smoke` dispatches can opt into it, but pull requests and `main` pushes do not run it. QR and installer Docker tests keep their own install-focused Dockerfiles. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes in parallel with `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default concurrency of 4 with `OPENCLAW_DOCKER_ALL_PARALLELISM`. The local aggregate stops scheduling new pooled lanes after the first failure by default, and each lane has a 120-minute timeout overrideable with `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Startup- or provider-sensitive lanes run exclusively after the parallel pool. The reusable live/E2E workflow mirrors the shared-image pattern by building and pushing one SHA-tagged GHCR Docker E2E image before the Docker matrix, then running the matrix with `OPENCLAW_SKIP_DOCKER_BUILD=1`. The scheduled live/E2E workflow runs the full release-path Docker suite daily. The full bundled update/channel matrix remains manual/full-suite because it performs repeated real npm update and doctor repair passes.
+The separate `install-smoke` workflow reuses the same scope script through its own `preflight` job. It splits smoke coverage into `run_fast_install_smoke` and `run_full_install_smoke`. Pull requests run the fast path for Docker/package surfaces, bundled plugin package/manifest changes, and core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 120-second command timeout. The full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. `main` pushes, including merge commits, do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation. The slow Bun global install image-provider smoke is separately gated by `run_bun_global_install_smoke`; it runs on the nightly schedule and from the release checks workflow, and manual `install-smoke` dispatches can opt into it, but pull requests and `main` pushes do not run it. QR and installer Docker tests keep their own install-focused Dockerfiles. Local `test:docker:all` prebuilds one shared live-test image and one shared `scripts/e2e/Dockerfile` built-app image, then runs the live/E2E smoke lanes in parallel with `OPENCLAW_SKIP_DOCKER_BUILD=1`; tune the default main-pool concurrency of 8 with `OPENCLAW_DOCKER_ALL_PARALLELISM` and the provider-sensitive tail-pool concurrency of 8 with `OPENCLAW_DOCKER_ALL_TAIL_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`. 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.
 
@@ -136,3 +136,8 @@ node scripts/ci-run-timings.mjs --recent 10   # compare recent successful main C
 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
 pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
 ```
+
+## Related
+
+- [Install overview](/install)
+- [Release channels](/install/development-channels)

docs/cli/acp.md

@@ -314,3 +314,8 @@ Security note:
 - `--server-args <args...>`: extra arguments passed to the ACP server.
 - `--server-verbose`: enable verbose logging on the ACP server.
 - `--verbose, -v`: verbose client logging.
+
+## Related
+
+- [CLI reference](/cli)
+- [ACP agents](/tools/acp-agents)

docs/cli/backup.md

@@ -82,3 +82,7 @@ Practical limits come from the local machine and destination filesystem:
 Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
 
 For the smallest archive, use `--only-config`.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/browser.md

@@ -245,3 +245,8 @@ If the Gateway runs on a different machine than the browser, run a **node host**
 Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
 
 Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)
+
+## Related
+
+- [CLI reference](/cli)
+- [Browser](/tools/browser)

docs/cli/clawbot.md

@@ -19,3 +19,7 @@ Current supported alias:
 Prefer modern top-level commands directly:
 
 - `openclaw clawbot qr` -> `openclaw qr`
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/completion.md

@@ -33,3 +33,7 @@ openclaw completion --shell bash --write-state
 - `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script.
 - Without `--install` or `--write-state`, the command prints the script to stdout.
 - Completion generation eagerly loads command trees so nested subcommands are included.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/configure.md

@@ -70,3 +70,8 @@ openclaw configure --section web
 openclaw configure --section model --section channels
 openclaw configure --section gateway --section daemon
 ```
+
+## Related
+
+- [CLI reference](/cli)
+- [Configuration](/gateway/configuration)

docs/cli/cron.md

@@ -174,3 +174,8 @@ Failure-delivery note:
   delivery mode is `webhook`.
 - If you do not set any failure destination and the job already announces to a
   channel, failure notifications reuse that same announce target.
+
+## Related
+
+- [CLI reference](/cli)
+- [Scheduled tasks](/automation/cron-jobs)

docs/cli/daemon.md

@@ -55,3 +55,8 @@ Notes:
 ## Prefer
 
 Use [`openclaw gateway`](/cli/gateway) for current docs and examples.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway runbook](/gateway)

docs/cli/dashboard.md

@@ -20,3 +20,8 @@ Notes:
 - `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
 - For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
 - If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.
+
+## Related
+
+- [CLI reference](/cli)
+- [Dashboard](/web/dashboard)

docs/cli/devices.md

@@ -178,3 +178,8 @@ Related:
 
 - [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
 - [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

docs/cli/directory.md

@@ -61,3 +61,7 @@ openclaw directory groups list --channel zalouser
 openclaw directory groups list --channel zalouser --query "work"
 openclaw directory groups members --channel zalouser --group-id <id>
 ```
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/dns.md

@@ -46,3 +46,8 @@ Notes:
 - If `--domain` is omitted, OpenClaw uses `discovery.wideArea.domain` from config.
 - `--apply` currently supports macOS only and expects Homebrew CoreDNS.
 - `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.
+
+## Related
+
+- [CLI reference](/cli)
+- [Discovery](/gateway/discovery)

docs/cli/docs.md

@@ -26,3 +26,7 @@ Notes:
 
 - With no query, `openclaw docs` opens the live docs search entrypoint.
 - Multi-word queries are passed through as one search request.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/doctor.md

@@ -63,3 +63,8 @@ launchctl getenv OPENCLAW_GATEWAY_PASSWORD
 launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
 launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
 ```
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway doctor](/gateway/doctor)

docs/cli/flows.md

@@ -16,3 +16,8 @@ openclaw tasks flow cancel <lookup>
 ```
 
 For full documentation see [Task Flow](/automation/taskflow) and the [tasks CLI reference](/cli/tasks).
+
+## Related
+
+- [CLI reference](/cli)
+- [Automation](/automation)

docs/cli/gateway.md

@@ -371,3 +371,8 @@ Notes:
 - On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when
   `discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort`
   stays optional there too.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway runbook](/gateway)

docs/cli/health.md

@@ -34,3 +34,8 @@ Notes:
 - `--verbose` forces a live probe, prints gateway connection details, and expands the
   human-readable output across all configured accounts and agents.
 - Output includes per-agent session stores when multiple agents are configured.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway health](/gateway/health)

docs/cli/logs.md

@@ -57,3 +57,8 @@ openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
 
 - Use `--local-time` to render timestamps in your local timezone.
 - If the local loopback Gateway asks for pairing, `openclaw logs` falls back to the configured local log file automatically. Explicit `--url` targets do not use this fallback.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway logging](/gateway/logging)

docs/cli/memory.md

@@ -174,3 +174,8 @@ Notes:
 - `memory rem-backfill --path <file-or-dir> --stage-short-term` also seeds grounded durable candidates into the live short-term promotion store so the normal deep phase can rank them.
 - `memory rem-backfill --rollback` removes previously written grounded diary entries, and `memory rem-backfill --rollback-short-term` removes previously staged grounded short-term candidates.
 - See [Dreaming](/concepts/dreaming) for full phase descriptions and configuration reference.
+
+## Related
+
+- [CLI reference](/cli)
+- [Memory overview](/concepts/memory)

docs/cli/message.md

@@ -296,3 +296,8 @@ Send a Telegram image as a document to avoid compression:
 openclaw message send --channel telegram --target @mychat \
   --media ./diagram.png --force-document
 ```
+
+## Related
+
+- [CLI reference](/cli)
+- [Agent send](/tools/agent-send)

docs/cli/node.md

@@ -74,6 +74,11 @@ Options:
 - In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
 - Node host auth resolution only honors `OPENCLAW_GATEWAY_*` env vars.
 
+For a node connecting to a non-loopback `ws://` Gateway on a trusted private
+network, set `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`. Without it, node startup
+fails closed and asks you to use `wss://`, an SSH tunnel, or Tailscale.
+`openclaw node install` persists this opt-in into the supervised node service.
+
 ## Service (background)
 
 Install a headless node host as a user service.
@@ -135,3 +140,8 @@ For approved async node exec, OpenClaw prepares a canonical `systemRunPlan`
 before prompting. The later approved `system.run` forward reuses that stored
 plan, so edits to command/cwd/session fields after the approval request was
 created are rejected instead of changing what the node executes.
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

docs/cli/proxy.md

@@ -43,3 +43,8 @@ openclaw proxy purge
 - `start` defaults to `127.0.0.1` unless `--host` is set.
 - `run` starts a local debug proxy and then runs the command after `--`.
 - Captures are local debugging data; use `openclaw proxy purge` when finished.
+
+## Related
+
+- [CLI reference](/cli)
+- [Trusted proxy auth](/gateway/trusted-proxy-auth)

docs/cli/qr.md

@@ -50,3 +50,8 @@ openclaw qr --url wss://gateway.example/ws
 - After scanning, approve device pairing with:
   - `openclaw devices list`
   - `openclaw devices approve <requestId>`
+
+## Related
+
+- [CLI reference](/cli)
+- [Pairing](/cli/pairing)

docs/cli/reset.md

@@ -33,3 +33,7 @@ Notes:
 - Run `openclaw backup create` first if you want a restorable snapshot before removing local state.
 - If you omit `--scope`, `openclaw reset` uses an interactive prompt to choose what to remove.
 - `--non-interactive` is only valid when both `--scope` and `--yes` are set.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/sandbox.md

@@ -188,13 +188,9 @@ Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sand
 }
 ```
 
-## See Also
-
-- [Sandbox Documentation](/gateway/sandboxing)
-- [Agent Configuration](/concepts/agent-workspace)
-- [Doctor Command](/gateway/doctor) - Check sandbox setup
-
 ## Related
 
 - [CLI reference](/cli)
 - [Sandboxing](/gateway/sandboxing)
+- [Agent workspace](/concepts/agent-workspace)
+- [Doctor](/gateway/doctor) — checks sandbox setup

docs/cli/secrets.md

@@ -195,3 +195,8 @@ openclaw secrets audit --check
 ```
 
 If `audit --check` still reports plaintext findings, update the remaining reported target paths and rerun audit.
+
+## Related
+
+- [CLI reference](/cli)
+- [Secrets management](/gateway/secrets)

docs/cli/security.md

@@ -84,3 +84,8 @@ openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summa
 - disable tools (`gateway`, `cron`, `exec`, etc.)
 - change gateway bind/auth/network exposure choices
 - remove or rewrite plugins/skills
+
+## Related
+
+- [CLI reference](/cli)
+- [Security audit](/gateway/security)

docs/cli/setup.md

@@ -43,3 +43,8 @@ Notes:
 
 - Plain `openclaw setup` initializes config + workspace without the full onboarding flow.
 - Onboarding auto-runs when any onboarding flags are present (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).
+
+## Related
+
+- [CLI reference](/cli)
+- [Install overview](/install)

docs/cli/system.md

@@ -69,3 +69,7 @@ Flags:
 
 - Requires a running Gateway reachable by your current config (local or remote).
 - System events are ephemeral and not persisted across restarts.
+
+## Related
+
+- [CLI reference](/cli)

docs/cli/tasks.md

@@ -94,3 +94,8 @@ openclaw tasks flow cancel <lookup>
 ```
 
 Inspects or cancels durable Task Flow state under the task ledger.
+
+## Related
+
+- [CLI reference](/cli)
+- [Background tasks](/automation/tasks)

docs/cli/tui.md

@@ -65,3 +65,8 @@ Then inside the TUI:
 
 Apply targeted fixes with `openclaw config set` or `openclaw configure`, then
 rerun `openclaw config validate`. See [TUI](/web/tui) and [Config](/cli/config).
+
+## Related
+
+- [CLI reference](/cli)
+- [TUI](/web/tui)

docs/cli/uninstall.md

@@ -37,3 +37,8 @@ Notes:
 - Run `openclaw backup create` first if you want a restorable snapshot before removing state or workspaces.
 - `--all` is shorthand for removing service, state, workspace, and app together.
 - `--non-interactive` requires `--yes`.
+
+## Related
+
+- [CLI reference](/cli)
+- [Uninstall](/install/uninstall)

docs/cli/voicecall.md

@@ -33,3 +33,8 @@ openclaw voicecall expose --mode off
 ```
 
 Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
+
+## Related
+
+- [CLI reference](/cli)
+- [Voice call plugin](/plugins/voice-call)

docs/cli/webhooks.md

@@ -89,3 +89,8 @@ openclaw webhooks gmail run --account you@example.com
 ```
 
 See [Gmail Pub/Sub documentation](/automation/cron-jobs#gmail-pubsub-integration) for the end-to-end setup flow and operational details.
+
+## Related
+
+- [CLI reference](/cli)
+- [Webhook automation](/automation/webhook)

docs/cli/wiki.md

@@ -212,3 +212,8 @@ These require the official `obsidian` CLI on `PATH` when
 - `plugins.entries.memory-wiki.config.context.includeCompiledDigestPrompt`
 
 See [Memory Wiki plugin](/plugins/memory-wiki) for the full config model.
+
+## Related
+
+- [CLI reference](/cli)
+- [Memory wiki](/plugins/memory-wiki)

docs/concepts/agent.md

@@ -5,7 +5,10 @@ read_when:
 title: "Agent runtime"
 ---
 
-OpenClaw runs a single embedded agent runtime.
+OpenClaw runs a **single embedded agent runtime** — one agent process per
+Gateway, with its own workspace, bootstrap files, and session store. This page
+covers that runtime contract: what the workspace must contain, which files get
+injected, and how sessions bootstrap against it.
 
 ## Workspace (required)
 

docs/concepts/compaction.md

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

docs/concepts/context-engine.md

@@ -77,6 +77,10 @@ four lifecycle points:
 4. **After turn** — called after a run completes. The engine can persist state,
    trigger background compaction, or update indexes.
 
+For the bundled non-ACP Codex harness, OpenClaw applies the same lifecycle by
+projecting assembled context into Codex developer instructions and the current
+turn prompt. Codex still owns its native thread history and native compactor.
+
 ### Subagent lifecycle (optional)
 
 OpenClaw calls two optional subagent lifecycle hooks:

docs/concepts/context.md

@@ -147,7 +147,7 @@ What persists across messages depends on the mechanism:
 
 - **Normal history** persists in the session transcript until compacted/pruned by policy.
 - **Compaction** persists a summary into the transcript and keeps recent messages intact.
-- **Pruning** removes old tool results from the _in-memory_ prompt for a run, but does not rewrite the transcript.
+- **Pruning** drops old tool results from the _in-memory_ prompt to free context-window space, but does not rewrite the session transcript — the full history is still inspectable on disk.
 
 Docs: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning).
 

docs/concepts/dreaming.md

@@ -227,20 +227,8 @@ When enabled, the Gateway **Dreams** tab shows:
 - a distinct grounded Scene lane for staged historical replay entries
 - an expandable Dream Diary reader backed by `doctor.memory.dreamDiary`
 
-## Troubleshooting
-
-### Dreaming never runs (status shows blocked)
-
-The managed dreaming cron rides the default agent's heartbeat. If heartbeat is not firing for that agent, the cron enqueues a system event that nobody consumes and dreaming silently does not run. Both `openclaw memory status` and `/dreaming status` will report `blocked` in that case and name the agent whose heartbeat is the blocker.
-
-Two common causes:
-
-- Another agent declares an explicit `heartbeat:` block. When any entry in `agents.list` has its own `heartbeat` block, only those agents heartbeat — the defaults stop applying to everyone else, so the default agent can go silent. Move the heartbeat settings to `agents.defaults.heartbeat`, or add an explicit `heartbeat` block on the default agent. See [Scope and precedence](/gateway/heartbeat#scope-and-precedence).
-- `heartbeat.every` is `0`, empty, or unparsable. The cron has no interval to schedule against, so the heartbeat is effectively disabled. Set `every` to a positive duration such as `30m`. See [Defaults](/gateway/heartbeat#defaults).
-
 ## Related
 
-- [Heartbeat](/gateway/heartbeat)
 - [Memory](/concepts/memory)
 - [Memory Search](/concepts/memory-search)
 - [memory CLI](/cli/memory)

docs/concepts/experimental-features.md

@@ -25,7 +25,7 @@ Treat them differently from normal config:
 | ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | Local model runtime      | `agents.defaults.experimental.localModelLean`             | A smaller or stricter local backend chokes on OpenClaw's full default tool surface                             | [Local Models](/gateway/local-models)                                                         |
 | Memory search            | `agents.defaults.memorySearch.experimental.sessionMemory` | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost         | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
-| Structured planning tool | `tools.experimental.planTool`                             | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs | [Gateway configuration reference](/gateway/configuration-reference#toolsexperimental)         |
+| Structured planning tool | `tools.experimental.planTool`                             | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs | [Gateway configuration reference](/gateway/config-tools#toolsexperimental)                    |
 
 ## Local model lean mode
 

docs/concepts/model-providers.md

@@ -21,6 +21,9 @@ For model selection rules, see [/concepts/models](/concepts/models).
   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).
+- Plugin auto-enable follows that same boundary: `openai-codex/<model>` belongs
+  to the OpenAI plugin, while the Codex plugin is enabled by
+  `embeddedHarness.runtime: "codex"` or legacy `codex/<model>` refs.
 - 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
@@ -110,6 +113,9 @@ OpenClaw ships with the pi‑ai catalog. These providers require **no**
 - 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-*`
+- Plugin boundary: `openai-codex/*` loads the OpenAI plugin; the native Codex
+  app-server plugin is selected only by the Codex harness runtime or legacy
+  `codex/*` refs.
 - 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 PI model via `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"`, or `"auto"`)

docs/debug/node-issue.md

@@ -83,3 +83,8 @@ node --import tsx scripts/repro/tsx-name-repro.ts
 - Repro on Node 22/24 to confirm Node 25 regression.
 - Test `tsx` nightly or pin to earlier version if a known regression exists.
 - If reproduces on Node LTS, file a minimal repro upstream with the `__name` stack trace.
+
+## Related
+
+- [Node.js install](/install/node)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/diagnostics/flags.md

@@ -87,3 +87,8 @@ For remote gateways, you can also use `openclaw logs --follow` (see [/cli/logs](
 - If `logging.level` is set higher than `warn`, these logs may be suppressed. Default `info` is fine.
 - Flags are safe to leave enabled; they only affect log volume for the specific subsystem.
 - Use [/logging](/logging) to change log destinations, levels, and redaction.
+
+## Related
+
+- [Gateway diagnostics](/gateway/diagnostics)
+- [Gateway troubleshooting](/gateway/troubleshooting)

docs/docs.json

@@ -60,6 +60,10 @@
       "source": "/providers/modelstudio",
       "destination": "/providers/qwen"
     },
+    {
+      "source": "/providers/qwen_modelstudio",
+      "destination": "/providers/qwen"
+    },
     {
       "source": "/platforms/oracle",
       "destination": "/install/oracle"
@@ -1004,6 +1008,10 @@
                   "install/uninstall",
                   "install/development-channels"
                 ]
+              },
+              {
+                "group": "Advanced setup",
+                "pages": ["start/setup", "pi-dev"]
               }
             ]
           },
@@ -1015,30 +1023,40 @@
                 "pages": ["channels/index"]
               },
               {
-                "group": "Messaging platforms",
+                "group": "Mainstream messaging",
                 "pages": [
-                  "channels/bluebubbles",
                   "channels/discord",
-                  "channels/feishu",
+                  "channels/slack",
+                  "channels/telegram",
+                  "channels/whatsapp",
+                  "channels/signal",
+                  "channels/msteams",
                   "channels/googlechat",
                   "channels/imessage",
-                  "channels/irc",
-                  "channels/line",
+                  "channels/bluebubbles",
                   "channels/matrix",
-                  "channels/matrix-push-rules",
+                  "channels/matrix-push-rules"
+                ]
+              },
+              {
+                "group": "Developer and self-hosted",
+                "pages": [
+                  "channels/irc",
                   "channels/mattermost",
-                  "channels/msteams",
                   "channels/nextcloud-talk",
                   "channels/nostr",
-                  "channels/qqbot",
-                  "channels/signal",
-                  "channels/slack",
-                  "channels/synology-chat",
-                  "channels/telegram",
                   "channels/tlon",
-                  "channels/twitch",
+                  "channels/synology-chat",
+                  "channels/twitch"
+                ]
+              },
+              {
+                "group": "Regional platforms",
+                "pages": [
+                  "channels/line",
                   "channels/wechat",
-                  "channels/whatsapp",
+                  "channels/qqbot",
+                  "channels/feishu",
                   "channels/zalo",
                   "channels/zalouser"
                 ]
@@ -1052,7 +1070,8 @@
                   "channels/broadcast-groups",
                   "channels/channel-routing",
                   "channels/location",
-                  "channels/troubleshooting"
+                  "channels/troubleshooting",
+                  "channels/qa-channel"
                 ]
               }
             ]
@@ -1136,7 +1155,7 @@
                   "plugins/memory-wiki",
                   "plugins/zalouser",
                   {
-                    "group": "Building Plugins",
+                    "group": "Building plugins",
                     "pages": [
                       "plugins/building-plugins",
                       "plugins/sdk-channel-plugins",
@@ -1145,7 +1164,7 @@
                     ]
                   },
                   {
-                    "group": "SDK Reference",
+                    "group": "SDK reference",
                     "pages": [
                       "plugins/sdk-overview",
                       "plugins/sdk-subpaths",
@@ -1173,7 +1192,7 @@
                 ]
               },
               {
-                "group": "Automation & Tasks",
+                "group": "Automation and tasks",
                 "pages": [
                   "automation/index",
                   "automation/cron-jobs",
@@ -1207,7 +1226,7 @@
                   "tools/trajectory",
                   "tools/video-generation",
                   {
-                    "group": "Web Browser",
+                    "group": "Web browser",
                     "pages": [
                       "tools/browser",
                       "tools/browser-control",
@@ -1217,7 +1236,7 @@
                     ]
                   },
                   {
-                    "group": "Web Tools",
+                    "group": "Web tools",
                     "pages": [
                       "tools/web-fetch",
                       "tools/web",
@@ -1333,23 +1352,38 @@
               {
                 "group": "macOS companion app",
                 "pages": [
-                  "platforms/mac/dev-setup",
-                  "platforms/mac/menu-bar",
-                  "platforms/mac/voicewake",
-                  "platforms/mac/voice-overlay",
-                  "platforms/mac/webchat",
-                  "platforms/mac/canvas",
-                  "platforms/mac/child-process",
-                  "platforms/mac/health",
-                  "platforms/mac/icon",
-                  "platforms/mac/logging",
-                  "platforms/mac/permissions",
-                  "platforms/mac/remote",
-                  "platforms/mac/signing",
-                  "platforms/mac/bundled-gateway",
-                  "platforms/mac/xpc",
-                  "platforms/mac/skills",
-                  "platforms/mac/peekaboo"
+                  {
+                    "group": "Setup",
+                    "pages": [
+                      "platforms/mac/dev-setup",
+                      "platforms/mac/menu-bar",
+                      "platforms/mac/icon",
+                      "platforms/mac/permissions",
+                      "platforms/mac/signing"
+                    ]
+                  },
+                  {
+                    "group": "Runtime",
+                    "pages": [
+                      "platforms/mac/bundled-gateway",
+                      "platforms/mac/child-process",
+                      "platforms/mac/health",
+                      "platforms/mac/logging",
+                      "platforms/mac/remote",
+                      "platforms/mac/xpc"
+                    ]
+                  },
+                  {
+                    "group": "Features",
+                    "pages": [
+                      "platforms/mac/voicewake",
+                      "platforms/mac/voice-overlay",
+                      "platforms/mac/webchat",
+                      "platforms/mac/canvas",
+                      "platforms/mac/skills",
+                      "platforms/mac/peekaboo"
+                    ]
+                  }
                 ]
               }
             ]
@@ -1362,28 +1396,44 @@
                 "pages": [
                   "gateway/index",
                   {
-                    "group": "Configuration and operations",
+                    "group": "Configuration",
                     "pages": [
                       "gateway/configuration",
                       "gateway/configuration-reference",
                       "gateway/config-agents",
                       "gateway/config-channels",
-                      "gateway/configuration-examples",
+                      "gateway/config-tools",
+                      "gateway/configuration-examples"
+                    ]
+                  },
+                  {
+                    "group": "Authentication and secrets",
+                    "pages": [
                       "gateway/authentication",
                       "auth-credential-semantics",
                       "gateway/secrets",
                       "gateway/secrets-plan-contract",
-                      "gateway/trusted-proxy-auth",
+                      "gateway/trusted-proxy-auth"
+                    ]
+                  },
+                  {
+                    "group": "Health and diagnostics",
+                    "pages": [
                       "gateway/health",
                       "gateway/diagnostics",
                       "gateway/heartbeat",
                       "gateway/doctor",
                       "gateway/logging",
                       "logging",
+                      "gateway/troubleshooting"
+                    ]
+                  },
+                  {
+                    "group": "Scaling and operations",
+                    "pages": [
                       "gateway/gateway-lock",
                       "gateway/background-process",
-                      "gateway/multiple-gateways",
-                      "gateway/troubleshooting"
+                      "gateway/multiple-gateways"
                     ]
                   },
                   {
@@ -1579,6 +1629,7 @@
                   "reference/transcript-hygiene",
                   "reference/memory-config",
                   "reference/rich-output-protocol",
+                  "reference/session-management-compaction",
                   "date-time"
                 ]
               },
@@ -1597,8 +1648,8 @@
                 "pages": ["reference/credits"]
               },
               {
-                "group": "Release policy",
-                "pages": ["reference/RELEASING", "reference/test"]
+                "group": "Release and CI",
+                "pages": ["reference/RELEASING", "reference/test", "ci", "help/scripts"]
               }
             ]
           },
@@ -1606,40 +1657,24 @@
             "tab": "Help",
             "groups": [
               {
-                "group": "Help",
-                "pages": ["help/index", "help/troubleshooting", "help/faq"]
+                "group": "Start here",
+                "pages": ["help/index", "help/troubleshooting", "help/debugging"]
               },
               {
-                "group": "Community",
-                "pages": ["start/lore"]
+                "group": "FAQ",
+                "pages": ["help/faq", "help/faq-first-run", "help/faq-models"]
               },
               {
-                "group": "Environment and debugging",
-                "pages": [
-                  "help/environment",
-                  "help/debugging",
-                  "help/testing",
-                  "help/testing-live",
-                  "help/scripts",
-                  "debug/node-issue",
-                  "diagnostics/flags"
-                ]
+                "group": "Testing",
+                "pages": ["help/testing", "help/testing-live"]
               },
               {
-                "group": "Compaction internals",
-                "pages": ["reference/session-management-compaction"]
+                "group": "Diagnostics",
+                "pages": ["help/environment", "diagnostics/flags", "debug/node-issue"]
               },
               {
-                "group": "Developer setup",
-                "pages": ["start/setup", "pi-dev"]
-              },
-              {
-                "group": "Contributing",
-                "pages": ["ci"]
-              },
-              {
-                "group": "Docs meta",
-                "pages": ["start/hubs", "start/docs-directory"]
+                "group": "Community and meta",
+                "pages": ["start/lore", "start/hubs", "start/docs-directory"]
               }
             ]
           }

docs/gateway/background-process.md

@@ -129,3 +129,8 @@ Paste literal text:
 ```json
 { "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
 ```
+
+## Related
+
+- [Exec tool](/tools/exec)
+- [Exec approvals](/tools/exec-approvals)

docs/gateway/bridge-protocol.md

@@ -87,3 +87,8 @@ Payload fields (all optional unless noted):
 The bridge was **implicit v1** (no min/max negotiation). This section is
 historical reference only; current node/operator clients use the WebSocket
 [Gateway Protocol](/gateway/protocol).
+
+## Related
+
+- [Gateway protocol](/gateway/protocol)
+- [Nodes](/nodes)

docs/gateway/cli-backends.md

@@ -370,3 +370,8 @@ backend opts into bundle MCP so background runs stay isolated.
 - **No session continuity**: ensure `sessionArg` is set and `sessionMode` is not
   `none` (Codex CLI currently cannot resume with JSON output).
 - **Images ignored**: set `imageArg` (and verify CLI supports file paths).
+
+## Related
+
+- [Gateway runbook](/gateway)
+- [Local models](/gateway/local-models)

docs/gateway/config-tools.md

@@ -0,0 +1,667 @@
+---
+summary: "Tools config (policy, experimental toggles, provider-backed tools) and custom provider/base-URL setup"
+read_when:
+  - Configuring `tools.*` policy, allowlists, or experimental features
+  - Registering custom providers or overriding base URLs
+  - Setting up OpenAI-compatible self-hosted endpoints
+title: "Configuration — tools and custom providers"
+---
+
+`tools.*` config keys and custom provider / base-URL setup. For agents,
+channels, and other top-level config keys, see
+[Configuration reference](/gateway/configuration-reference).
+
+## Tools
+
+### Tool profiles
+
+`tools.profile` sets a base allowlist before `tools.allow`/`tools.deny`:
+
+Local onboarding defaults new local configs to `tools.profile: "coding"` when unset (existing explicit profiles are preserved).
+
+| Profile     | Includes                                                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal`   | `session_status` only                                                                                                           |
+| `coding`    | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
+| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`                                       |
+| `full`      | No restriction (same as unset)                                                                                                  |
+
+### Tool groups
+
+| Group              | Tools                                                                                                                   |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `group:runtime`    | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`)                                         |
+| `group:fs`         | `read`, `write`, `edit`, `apply_patch`                                                                                  |
+| `group:sessions`   | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
+| `group:memory`     | `memory_search`, `memory_get`                                                                                           |
+| `group:web`        | `web_search`, `x_search`, `web_fetch`                                                                                   |
+| `group:ui`         | `browser`, `canvas`                                                                                                     |
+| `group:automation` | `cron`, `gateway`                                                                                                       |
+| `group:messaging`  | `message`                                                                                                               |
+| `group:nodes`      | `nodes`                                                                                                                 |
+| `group:agents`     | `agents_list`                                                                                                           |
+| `group:media`      | `image`, `image_generate`, `video_generate`, `tts`                                                                      |
+| `group:openclaw`   | All built-in tools (excludes provider plugins)                                                                          |
+
+### `tools.allow` / `tools.deny`
+
+Global tool allow/deny policy (deny wins). Case-insensitive, supports `*` wildcards. Applied even when Docker sandbox is off.
+
+```json5
+{
+  tools: { deny: ["browser", "canvas"] },
+}
+```
+
+### `tools.byProvider`
+
+Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    byProvider: {
+      "google-antigravity": { profile: "minimal" },
+      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
+    },
+  },
+}
+```
+
+### `tools.elevated`
+
+Controls elevated exec access outside the sandbox:
+
+```json5
+{
+  tools: {
+    elevated: {
+      enabled: true,
+      allowFrom: {
+        whatsapp: ["+15555550123"],
+        discord: ["1234567890123", "987654321098765432"],
+      },
+    },
+  },
+}
+```
+
+- Per-agent override (`agents.list[].tools.elevated`) can only further restrict.
+- `/elevated on|off|ask|full` stores state per session; inline directives apply to single message.
+- Elevated `exec` bypasses sandboxing and uses the configured escape path (`gateway` by default, or `node` when the exec target is `node`).
+
+### `tools.exec`
+
+```json5
+{
+  tools: {
+    exec: {
+      backgroundMs: 10000,
+      timeoutSec: 1800,
+      cleanupMs: 1800000,
+      notifyOnExit: true,
+      notifyOnExitEmptySuccess: false,
+      applyPatch: {
+        enabled: false,
+        allowModels: ["gpt-5.5"],
+      },
+    },
+  },
+}
+```
+
+### `tools.loopDetection`
+
+Tool-loop safety checks are **disabled by default**. Set `enabled: true` to activate detection.
+Settings can be defined globally in `tools.loopDetection` and overridden per-agent at `agents.list[].tools.loopDetection`.
+
+```json5
+{
+  tools: {
+    loopDetection: {
+      enabled: true,
+      historySize: 30,
+      warningThreshold: 10,
+      criticalThreshold: 20,
+      globalCircuitBreakerThreshold: 30,
+      detectors: {
+        genericRepeat: true,
+        knownPollNoProgress: true,
+        pingPong: true,
+      },
+    },
+  },
+}
+```
+
+- `historySize`: max tool-call history retained for loop analysis.
+- `warningThreshold`: repeating no-progress pattern threshold for warnings.
+- `criticalThreshold`: higher repeating threshold for blocking critical loops.
+- `globalCircuitBreakerThreshold`: hard stop threshold for any no-progress run.
+- `detectors.genericRepeat`: warn on repeated same-tool/same-args calls.
+- `detectors.knownPollNoProgress`: warn/block on known poll tools (`process.poll`, `command_status`, etc.).
+- `detectors.pingPong`: warn/block on alternating no-progress pair patterns.
+- If `warningThreshold >= criticalThreshold` or `criticalThreshold >= globalCircuitBreakerThreshold`, validation fails.
+
+### `tools.web`
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        apiKey: "brave_api_key", // or BRAVE_API_KEY env
+        maxResults: 5,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+      },
+      fetch: {
+        enabled: true,
+        provider: "firecrawl", // optional; omit for auto-detect
+        maxChars: 50000,
+        maxCharsCap: 50000,
+        maxResponseBytes: 2000000,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+        maxRedirects: 3,
+        readability: true,
+        userAgent: "custom-ua",
+      },
+    },
+  },
+}
+```
+
+### `tools.media`
+
+Configures inbound media understanding (image/audio/video):
+
+```json5
+{
+  tools: {
+    media: {
+      concurrency: 2,
+      asyncCompletion: {
+        directSend: false, // opt-in: send finished async music/video directly to the channel
+      },
+      audio: {
+        enabled: true,
+        maxBytes: 20971520,
+        scope: {
+          default: "deny",
+          rules: [{ action: "allow", match: { chatType: "direct" } }],
+        },
+        models: [
+          { provider: "openai", model: "gpt-4o-mini-transcribe" },
+          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
+        ],
+      },
+      video: {
+        enabled: true,
+        maxBytes: 52428800,
+        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
+      },
+    },
+  },
+}
+```
+
+<Accordion title="Media model entry fields">
+
+**Provider entry** (`type: "provider"` or omitted):
+
+- `provider`: API provider id (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
+- `model`: model id override
+- `profile` / `preferredProfile`: `auth-profiles.json` profile selection
+
+**CLI entry** (`type: "cli"`):
+
+- `command`: executable to run
+- `args`: templated args (supports `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.)
+
+**Common fields:**
+
+- `capabilities`: optional list (`image`, `audio`, `video`). Defaults: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
+- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: per-entry overrides.
+- Failures fall back to the next entry.
+
+Provider auth follows standard order: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
+
+**Async completion fields:**
+
+- `asyncCompletion.directSend`: when `true`, completed async `music_generate`
+  and `video_generate` tasks try direct channel delivery first. Default: `false`
+  (legacy requester-session wake/model-delivery path).
+
+</Accordion>
+
+### `tools.agentToAgent`
+
+```json5
+{
+  tools: {
+    agentToAgent: {
+      enabled: false,
+      allow: ["home", "work"],
+    },
+  },
+}
+```
+
+### `tools.sessions`
+
+Controls which sessions can be targeted by the session tools (`sessions_list`, `sessions_history`, `sessions_send`).
+
+Default: `tree` (current session + sessions spawned by it, such as subagents).
+
+```json5
+{
+  tools: {
+    sessions: {
+      // "self" | "tree" | "agent" | "all"
+      visibility: "tree",
+    },
+  },
+}
+```
+
+Notes:
+
+- `self`: only the current session key.
+- `tree`: current session + sessions spawned by the current session (subagents).
+- `agent`: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
+- `all`: any session. Cross-agent targeting still requires `tools.agentToAgent`.
+- Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility is forced to `tree` even if `tools.sessions.visibility="all"`.
+
+### `tools.sessions_spawn`
+
+Controls inline attachment support for `sessions_spawn`.
+
+```json5
+{
+  tools: {
+    sessions_spawn: {
+      attachments: {
+        enabled: false, // opt-in: set true to allow inline file attachments
+        maxTotalBytes: 5242880, // 5 MB total across all files
+        maxFiles: 50,
+        maxFileBytes: 1048576, // 1 MB per file
+        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Attachments are only supported for `runtime: "subagent"`. ACP runtime rejects them.
+- Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/` with a `.manifest.json`.
+- Attachment content is automatically redacted from transcript persistence.
+- Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
+- File permissions are `0700` for directories and `0600` for files.
+- Cleanup follows the `cleanup` policy: `delete` always removes attachments; `keep` retains them only when `retainOnSessionKeep: true`.
+
+<a id="toolsexperimental"></a>
+
+### `tools.experimental`
+
+Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto-enable rule applies.
+
+```json5
+{
+  tools: {
+    experimental: {
+      planTool: true, // enable experimental update_plan
+    },
+  },
+}
+```
+
+Notes:
+
+- `planTool`: enables the structured `update_plan` tool for non-trivial multi-step work tracking.
+- Default: `false` unless `agents.defaults.embeddedPi.executionContract` (or a per-agent override) is set to `"strict-agentic"` for an OpenAI or OpenAI Codex GPT-5-family run. Set `true` to force the tool on outside that scope, or `false` to keep it off even for strict-agentic GPT-5 runs.
+- When enabled, the system prompt also adds usage guidance so the model only uses it for substantial work and keeps at most one step `in_progress`.
+
+### `agents.defaults.subagents`
+
+```json5
+{
+  agents: {
+    defaults: {
+      subagents: {
+        allowAgents: ["research"],
+        model: "minimax/MiniMax-M2.7",
+        maxConcurrent: 8,
+        runTimeoutSeconds: 900,
+        archiveAfterMinutes: 60,
+      },
+    },
+  },
+}
+```
+
+- `model`: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
+- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any; default: same agent only).
+- `runTimeoutSeconds`: default timeout (seconds) for `sessions_spawn` when the tool call omits `runTimeoutSeconds`. `0` means no timeout.
+- Per-subagent tool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
+
+---
+
+## Custom providers and base URLs
+
+OpenClaw uses the built-in model catalog. Add custom providers via `models.providers` in config or `~/.openclaw/agents/<agentId>/agent/models.json`.
+
+```json5
+{
+  models: {
+    mode: "merge", // merge (default) | replace
+    providers: {
+      "custom-proxy": {
+        baseUrl: "http://localhost:4000/v1",
+        apiKey: "LITELLM_KEY",
+        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
+        models: [
+          {
+            id: "llama-3.1-8b",
+            name: "Llama 3.1 8B",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 128000,
+            contextTokens: 96000,
+            maxTokens: 32000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+- Use `authHeader: true` + `headers` for custom auth needs.
+- Override agent config root with `OPENCLAW_AGENT_DIR` (or `PI_CODING_AGENT_DIR`, a legacy environment variable alias).
+- Merge precedence for matching provider IDs:
+  - Non-empty agent `models.json` `baseUrl` values win.
+  - Non-empty agent `apiKey` values win only when that provider is not SecretRef-managed in current config/auth-profile context.
+  - SecretRef-managed provider `apiKey` values are refreshed from source markers (`ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs) instead of persisting resolved secrets.
+  - SecretRef-managed provider header values are refreshed from source markers (`secretref-env:ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs).
+  - Empty or missing agent `apiKey`/`baseUrl` fall back to `models.providers` in config.
+  - Matching model `contextWindow`/`maxTokens` use the higher value between explicit config and implicit catalog values.
+  - Matching model `contextTokens` preserves an explicit runtime cap when present; use it to limit effective context without changing native model metadata.
+  - Use `models.mode: "replace"` when you want config to fully rewrite `models.json`.
+  - Marker persistence is source-authoritative: markers are written from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
+
+### Provider field details
+
+- `models.mode`: provider catalog behavior (`merge` or `replace`).
+- `models.providers`: custom provider map keyed by provider id.
+  - Safe edits: use `openclaw config set models.providers.<id> '<json>' --strict-json --merge` or `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` for additive updates. `config set` refuses destructive replacements unless you pass `--replace`.
+- `models.providers.*.api`: request adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc).
+- `models.providers.*.apiKey`: provider credential (prefer SecretRef/env substitution).
+- `models.providers.*.auth`: auth strategy (`api-key`, `token`, `oauth`, `aws-sdk`).
+- `models.providers.*.injectNumCtxForOpenAICompat`: for Ollama + `openai-completions`, inject `options.num_ctx` into requests (default: `true`).
+- `models.providers.*.authHeader`: force credential transport in the `Authorization` header when required.
+- `models.providers.*.baseUrl`: upstream API base URL.
+- `models.providers.*.headers`: extra static headers for proxy/tenant routing.
+- `models.providers.*.request`: transport overrides for model-provider HTTP requests.
+  - `request.headers`: extra headers (merged with provider defaults). Values accept SecretRef.
+  - `request.auth`: auth strategy override. Modes: `"provider-default"` (use provider's built-in auth), `"authorization-bearer"` (with `token`), `"header"` (with `headerName`, `value`, optional `prefix`).
+  - `request.proxy`: HTTP proxy override. Modes: `"env-proxy"` (use `HTTP_PROXY`/`HTTPS_PROXY` env vars), `"explicit-proxy"` (with `url`). Both modes accept an optional `tls` sub-object.
+  - `request.tls`: TLS override for direct connections. Fields: `ca`, `cert`, `key`, `passphrase` (all accept SecretRef), `serverName`, `insecureSkipVerify`.
+  - `request.allowPrivateNetwork`: when `true`, allow HTTPS to `baseUrl` when DNS resolves to private, CGNAT, or similar ranges, via the provider HTTP fetch guard (operator opt-in for trusted self-hosted OpenAI-compatible endpoints). WebSocket uses the same `request` for headers/TLS but not that fetch SSRF gate. Default `false`.
+- `models.providers.*.models`: explicit provider model catalog entries.
+- `models.providers.*.models.*.contextWindow`: native model context window metadata.
+- `models.providers.*.models.*.contextTokens`: optional runtime context cap. Use this when you want a smaller effective context budget than the model's native `contextWindow`.
+- `models.providers.*.models.*.compat.supportsDeveloperRole`: optional compatibility hint. For `api: "openai-completions"` with a non-empty non-native `baseUrl` (host not `api.openai.com`), OpenClaw forces this to `false` at runtime. Empty/omitted `baseUrl` keeps default OpenAI behavior.
+- `models.providers.*.models.*.compat.requiresStringContent`: optional compatibility hint for string-only OpenAI-compatible chat endpoints. When `true`, OpenClaw flattens pure text `messages[].content` arrays into plain strings before sending the request.
+- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock auto-discovery settings root.
+- `plugins.entries.amazon-bedrock.config.discovery.enabled`: turn implicit discovery on/off.
+- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS region for discovery.
+- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optional provider-id filter for targeted discovery.
+- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: polling interval for discovery refresh.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: fallback context window for discovered models.
+- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: fallback max output tokens for discovered models.
+
+### Provider examples
+
+<Accordion title="Cerebras (GLM 4.6 / 4.7)">
+
+```json5
+{
+  env: { CEREBRAS_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: {
+        primary: "cerebras/zai-glm-4.7",
+        fallbacks: ["cerebras/zai-glm-4.6"],
+      },
+      models: {
+        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
+        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      cerebras: {
+        baseUrl: "https://api.cerebras.ai/v1",
+        apiKey: "${CEREBRAS_API_KEY}",
+        api: "openai-completions",
+        models: [
+          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
+          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
+        ],
+      },
+    },
+  },
+}
+```
+
+Use `cerebras/zai-glm-4.7` for Cerebras; `zai/glm-4.7` for Z.AI direct.
+
+</Accordion>
+
+<Accordion title="OpenCode">
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "opencode/claude-opus-4-6" },
+      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
+    },
+  },
+}
+```
+
+Set `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`). Use `opencode/...` refs for the Zen catalog or `opencode-go/...` refs for the Go catalog. Shortcut: `openclaw onboard --auth-choice opencode-zen` or `openclaw onboard --auth-choice opencode-go`.
+
+</Accordion>
+
+<Accordion title="Z.AI (GLM-4.7)">
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "zai/glm-4.7" },
+      models: { "zai/glm-4.7": {} },
+    },
+  },
+}
+```
+
+Set `ZAI_API_KEY`. `z.ai/*` and `z-ai/*` are accepted aliases. Shortcut: `openclaw onboard --auth-choice zai-api-key`.
+
+- General endpoint: `https://api.z.ai/api/paas/v4`
+- Coding endpoint (default): `https://api.z.ai/api/coding/paas/v4`
+- For the general endpoint, define a custom provider with the base URL override.
+
+</Accordion>
+
+<Accordion title="Moonshot AI (Kimi)">
+
+```json5
+{
+  env: { MOONSHOT_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "moonshot/kimi-k2.6" },
+      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      moonshot: {
+        baseUrl: "https://api.moonshot.ai/v1",
+        apiKey: "${MOONSHOT_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "kimi-k2.6",
+            name: "Kimi K2.6",
+            reasoning: false,
+            input: ["text", "image"],
+            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 262144,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+For the China endpoint: `baseUrl: "https://api.moonshot.cn/v1"` or `openclaw onboard --auth-choice moonshot-api-key-cn`.
+
+Native Moonshot endpoints advertise streaming usage compatibility on the shared
+`openai-completions` transport, and OpenClaw keys that off endpoint capabilities
+rather than the built-in provider id alone.
+
+</Accordion>
+
+<Accordion title="Kimi Coding">
+
+```json5
+{
+  env: { KIMI_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "kimi/kimi-code" },
+      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
+    },
+  },
+}
+```
+
+Anthropic-compatible, built-in provider. Shortcut: `openclaw onboard --auth-choice kimi-code-api-key`.
+
+</Accordion>
+
+<Accordion title="Synthetic (Anthropic-compatible)">
+
+```json5
+{
+  env: { SYNTHETIC_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
+      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      synthetic: {
+        baseUrl: "https://api.synthetic.new/anthropic",
+        apiKey: "${SYNTHETIC_API_KEY}",
+        api: "anthropic-messages",
+        models: [
+          {
+            id: "hf:MiniMaxAI/MiniMax-M2.5",
+            name: "MiniMax M2.5",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 192000,
+            maxTokens: 65536,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Base URL should omit `/v1` (Anthropic client appends it). Shortcut: `openclaw onboard --auth-choice synthetic-api-key`.
+
+</Accordion>
+
+<Accordion title="MiniMax M2.7 (direct)">
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "minimax/MiniMax-M2.7" },
+      models: {
+        "minimax/MiniMax-M2.7": { alias: "Minimax" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      minimax: {
+        baseUrl: "https://api.minimax.io/anthropic",
+        apiKey: "${MINIMAX_API_KEY}",
+        api: "anthropic-messages",
+        models: [
+          {
+            id: "MiniMax-M2.7",
+            name: "MiniMax M2.7",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
+            contextWindow: 204800,
+            maxTokens: 131072,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+Set `MINIMAX_API_KEY`. Shortcuts:
+`openclaw onboard --auth-choice minimax-global-api` or
+`openclaw onboard --auth-choice minimax-cn-api`.
+The model catalog defaults to M2.7 only.
+On the Anthropic-compatible streaming path, OpenClaw disables MiniMax thinking
+by default unless you explicitly set `thinking` yourself. `/fast on` or
+`params.fastMode: true` rewrites `MiniMax-M2.7` to
+`MiniMax-M2.7-highspeed`.
+
+</Accordion>
+
+<Accordion title="Local models (LM Studio)">
+
+See [Local Models](/gateway/local-models). TL;DR: run a large local model via LM Studio Responses API on serious hardware; keep hosted models merged for fallback.
+
+</Accordion>
+
+---
+
+## Related
+
+- [Configuration reference](/gateway/configuration-reference) — other top-level keys
+- [Configuration — agents](/gateway/config-agents)
+- [Configuration — channels](/gateway/config-channels)
+- [Tools and plugins](/tools)

docs/gateway/configuration-reference.md

@@ -43,654 +43,13 @@ Moved to a dedicated page — see
 - `session.*` (session lifecycle, compaction, pruning)
 - `messages.*` (message delivery, TTS, markdown rendering)
 - `talk.*` (Talk mode)
+  - `talk.silenceTimeoutMs`: when unset, Talk keeps the platform default pause window before sending the transcript (`700 ms on macOS and Android, 900 ms on iOS`)
 
-## Tools
+## Tools and custom providers
 
-### Tool profiles
-
-`tools.profile` sets a base allowlist before `tools.allow`/`tools.deny`:
-
-Local onboarding defaults new local configs to `tools.profile: "coding"` when unset (existing explicit profiles are preserved).
-
-| Profile     | Includes                                                                                                                        |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `minimal`   | `session_status` only                                                                                                           |
-| `coding`    | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
-| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`                                       |
-| `full`      | No restriction (same as unset)                                                                                                  |
-
-### Tool groups
-
-| Group              | Tools                                                                                                                   |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime`    | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`)                                         |
-| `group:fs`         | `read`, `write`, `edit`, `apply_patch`                                                                                  |
-| `group:sessions`   | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
-| `group:memory`     | `memory_search`, `memory_get`                                                                                           |
-| `group:web`        | `web_search`, `x_search`, `web_fetch`                                                                                   |
-| `group:ui`         | `browser`, `canvas`                                                                                                     |
-| `group:automation` | `cron`, `gateway`                                                                                                       |
-| `group:messaging`  | `message`                                                                                                               |
-| `group:nodes`      | `nodes`                                                                                                                 |
-| `group:agents`     | `agents_list`                                                                                                           |
-| `group:media`      | `image`, `image_generate`, `video_generate`, `tts`                                                                      |
-| `group:openclaw`   | All built-in tools (excludes provider plugins)                                                                          |
-
-### `tools.allow` / `tools.deny`
-
-Global tool allow/deny policy (deny wins). Case-insensitive, supports `*` wildcards. Applied even when Docker sandbox is off.
-
-```json5
-{
-  tools: { deny: ["browser", "canvas"] },
-}
-```
-
-### `tools.byProvider`
-
-Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.
-
-```json5
-{
-  tools: {
-    profile: "coding",
-    byProvider: {
-      "google-antigravity": { profile: "minimal" },
-      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
-    },
-  },
-}
-```
-
-### `tools.elevated`
-
-Controls elevated exec access outside the sandbox:
-
-```json5
-{
-  tools: {
-    elevated: {
-      enabled: true,
-      allowFrom: {
-        whatsapp: ["+15555550123"],
-        discord: ["1234567890123", "987654321098765432"],
-      },
-    },
-  },
-}
-```
-
-- Per-agent override (`agents.list[].tools.elevated`) can only further restrict.
-- `/elevated on|off|ask|full` stores state per session; inline directives apply to single message.
-- Elevated `exec` bypasses sandboxing and uses the configured escape path (`gateway` by default, or `node` when the exec target is `node`).
-
-### `tools.exec`
-
-```json5
-{
-  tools: {
-    exec: {
-      backgroundMs: 10000,
-      timeoutSec: 1800,
-      cleanupMs: 1800000,
-      notifyOnExit: true,
-      notifyOnExitEmptySuccess: false,
-      applyPatch: {
-        enabled: false,
-        allowModels: ["gpt-5.5"],
-      },
-    },
-  },
-}
-```
-
-### `tools.loopDetection`
-
-Tool-loop safety checks are **disabled by default**. Set `enabled: true` to activate detection.
-Settings can be defined globally in `tools.loopDetection` and overridden per-agent at `agents.list[].tools.loopDetection`.
-
-```json5
-{
-  tools: {
-    loopDetection: {
-      enabled: true,
-      historySize: 30,
-      warningThreshold: 10,
-      criticalThreshold: 20,
-      globalCircuitBreakerThreshold: 30,
-      detectors: {
-        genericRepeat: true,
-        knownPollNoProgress: true,
-        pingPong: true,
-      },
-    },
-  },
-}
-```
-
-- `historySize`: max tool-call history retained for loop analysis.
-- `warningThreshold`: repeating no-progress pattern threshold for warnings.
-- `criticalThreshold`: higher repeating threshold for blocking critical loops.
-- `globalCircuitBreakerThreshold`: hard stop threshold for any no-progress run.
-- `detectors.genericRepeat`: warn on repeated same-tool/same-args calls.
-- `detectors.knownPollNoProgress`: warn/block on known poll tools (`process.poll`, `command_status`, etc.).
-- `detectors.pingPong`: warn/block on alternating no-progress pair patterns.
-- If `warningThreshold >= criticalThreshold` or `criticalThreshold >= globalCircuitBreakerThreshold`, validation fails.
-
-### `tools.web`
-
-```json5
-{
-  tools: {
-    web: {
-      search: {
-        enabled: true,
-        apiKey: "brave_api_key", // or BRAVE_API_KEY env
-        maxResults: 5,
-        timeoutSeconds: 30,
-        cacheTtlMinutes: 15,
-      },
-      fetch: {
-        enabled: true,
-        provider: "firecrawl", // optional; omit for auto-detect
-        maxChars: 50000,
-        maxCharsCap: 50000,
-        maxResponseBytes: 2000000,
-        timeoutSeconds: 30,
-        cacheTtlMinutes: 15,
-        maxRedirects: 3,
-        readability: true,
-        userAgent: "custom-ua",
-      },
-    },
-  },
-}
-```
-
-### `tools.media`
-
-Configures inbound media understanding (image/audio/video):
-
-```json5
-{
-  tools: {
-    media: {
-      concurrency: 2,
-      asyncCompletion: {
-        directSend: false, // opt-in: send finished async music/video directly to the channel
-      },
-      audio: {
-        enabled: true,
-        maxBytes: 20971520,
-        scope: {
-          default: "deny",
-          rules: [{ action: "allow", match: { chatType: "direct" } }],
-        },
-        models: [
-          { provider: "openai", model: "gpt-4o-mini-transcribe" },
-          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
-        ],
-      },
-      video: {
-        enabled: true,
-        maxBytes: 52428800,
-        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
-      },
-    },
-  },
-}
-```
-
-<Accordion title="Media model entry fields">
-
-**Provider entry** (`type: "provider"` or omitted):
-
-- `provider`: API provider id (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
-- `model`: model id override
-- `profile` / `preferredProfile`: `auth-profiles.json` profile selection
-
-**CLI entry** (`type: "cli"`):
-
-- `command`: executable to run
-- `args`: templated args (supports `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.)
-
-**Common fields:**
-
-- `capabilities`: optional list (`image`, `audio`, `video`). Defaults: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
-- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: per-entry overrides.
-- Failures fall back to the next entry.
-
-Provider auth follows standard order: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
-
-**Async completion fields:**
-
-- `asyncCompletion.directSend`: when `true`, completed async `music_generate`
-  and `video_generate` tasks try direct channel delivery first. Default: `false`
-  (legacy requester-session wake/model-delivery path).
-
-</Accordion>
-
-### `tools.agentToAgent`
-
-```json5
-{
-  tools: {
-    agentToAgent: {
-      enabled: false,
-      allow: ["home", "work"],
-    },
-  },
-}
-```
-
-### `tools.sessions`
-
-Controls which sessions can be targeted by the session tools (`sessions_list`, `sessions_history`, `sessions_send`).
-
-Default: `tree` (current session + sessions spawned by it, such as subagents).
-
-```json5
-{
-  tools: {
-    sessions: {
-      // "self" | "tree" | "agent" | "all"
-      visibility: "tree",
-    },
-  },
-}
-```
-
-Notes:
-
-- `self`: only the current session key.
-- `tree`: current session + sessions spawned by the current session (subagents).
-- `agent`: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
-- `all`: any session. Cross-agent targeting still requires `tools.agentToAgent`.
-- Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility is forced to `tree` even if `tools.sessions.visibility="all"`.
-
-### `tools.sessions_spawn`
-
-Controls inline attachment support for `sessions_spawn`.
-
-```json5
-{
-  tools: {
-    sessions_spawn: {
-      attachments: {
-        enabled: false, // opt-in: set true to allow inline file attachments
-        maxTotalBytes: 5242880, // 5 MB total across all files
-        maxFiles: 50,
-        maxFileBytes: 1048576, // 1 MB per file
-        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
-      },
-    },
-  },
-}
-```
-
-Notes:
-
-- Attachments are only supported for `runtime: "subagent"`. ACP runtime rejects them.
-- Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/` with a `.manifest.json`.
-- Attachment content is automatically redacted from transcript persistence.
-- Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
-- File permissions are `0700` for directories and `0600` for files.
-- Cleanup follows the `cleanup` policy: `delete` always removes attachments; `keep` retains them only when `retainOnSessionKeep: true`.
-
-<a id="toolsexperimental"></a>
-
-### `tools.experimental`
-
-Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto-enable rule applies.
-
-```json5
-{
-  tools: {
-    experimental: {
-      planTool: true, // enable experimental update_plan
-    },
-  },
-}
-```
-
-Notes:
-
-- `planTool`: enables the structured `update_plan` tool for non-trivial multi-step work tracking.
-- Default: `false` unless `agents.defaults.embeddedPi.executionContract` (or a per-agent override) is set to `"strict-agentic"` for an OpenAI or OpenAI Codex GPT-5-family run. Set `true` to force the tool on outside that scope, or `false` to keep it off even for strict-agentic GPT-5 runs.
-- When enabled, the system prompt also adds usage guidance so the model only uses it for substantial work and keeps at most one step `in_progress`.
-
-### `agents.defaults.subagents`
-
-```json5
-{
-  agents: {
-    defaults: {
-      subagents: {
-        allowAgents: ["research"],
-        model: "minimax/MiniMax-M2.7",
-        maxConcurrent: 8,
-        runTimeoutSeconds: 900,
-        archiveAfterMinutes: 60,
-      },
-    },
-  },
-}
-```
-
-- `model`: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
-- `allowAgents`: default allowlist of target agent ids for `sessions_spawn` when the requester agent does not set its own `subagents.allowAgents` (`["*"]` = any; default: same agent only).
-- `runTimeoutSeconds`: default timeout (seconds) for `sessions_spawn` when the tool call omits `runTimeoutSeconds`. `0` means no timeout.
-- Per-subagent tool policy: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
-
----
-
-## Custom providers and base URLs
-
-OpenClaw uses the built-in model catalog. Add custom providers via `models.providers` in config or `~/.openclaw/agents/<agentId>/agent/models.json`.
-
-```json5
-{
-  models: {
-    mode: "merge", // merge (default) | replace
-    providers: {
-      "custom-proxy": {
-        baseUrl: "http://localhost:4000/v1",
-        apiKey: "LITELLM_KEY",
-        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
-        models: [
-          {
-            id: "llama-3.1-8b",
-            name: "Llama 3.1 8B",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 128000,
-            contextTokens: 96000,
-            maxTokens: 32000,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-- Use `authHeader: true` + `headers` for custom auth needs.
-- Override agent config root with `OPENCLAW_AGENT_DIR` (or `PI_CODING_AGENT_DIR`, a legacy environment variable alias).
-- Merge precedence for matching provider IDs:
-  - Non-empty agent `models.json` `baseUrl` values win.
-  - Non-empty agent `apiKey` values win only when that provider is not SecretRef-managed in current config/auth-profile context.
-  - SecretRef-managed provider `apiKey` values are refreshed from source markers (`ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs) instead of persisting resolved secrets.
-  - SecretRef-managed provider header values are refreshed from source markers (`secretref-env:ENV_VAR_NAME` for env refs, `secretref-managed` for file/exec refs).
-  - Empty or missing agent `apiKey`/`baseUrl` fall back to `models.providers` in config.
-  - Matching model `contextWindow`/`maxTokens` use the higher value between explicit config and implicit catalog values.
-  - Matching model `contextTokens` preserves an explicit runtime cap when present; use it to limit effective context without changing native model metadata.
-  - Use `models.mode: "replace"` when you want config to fully rewrite `models.json`.
-  - Marker persistence is source-authoritative: markers are written from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
-
-### Provider field details
-
-- `models.mode`: provider catalog behavior (`merge` or `replace`).
-- `models.providers`: custom provider map keyed by provider id.
-  - Safe edits: use `openclaw config set models.providers.<id> '<json>' --strict-json --merge` or `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` for additive updates. `config set` refuses destructive replacements unless you pass `--replace`.
-- `models.providers.*.api`: request adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc).
-- `models.providers.*.apiKey`: provider credential (prefer SecretRef/env substitution).
-- `models.providers.*.auth`: auth strategy (`api-key`, `token`, `oauth`, `aws-sdk`).
-- `models.providers.*.injectNumCtxForOpenAICompat`: for Ollama + `openai-completions`, inject `options.num_ctx` into requests (default: `true`).
-- `models.providers.*.authHeader`: force credential transport in the `Authorization` header when required.
-- `models.providers.*.baseUrl`: upstream API base URL.
-- `models.providers.*.headers`: extra static headers for proxy/tenant routing.
-- `models.providers.*.request`: transport overrides for model-provider HTTP requests.
-  - `request.headers`: extra headers (merged with provider defaults). Values accept SecretRef.
-  - `request.auth`: auth strategy override. Modes: `"provider-default"` (use provider's built-in auth), `"authorization-bearer"` (with `token`), `"header"` (with `headerName`, `value`, optional `prefix`).
-  - `request.proxy`: HTTP proxy override. Modes: `"env-proxy"` (use `HTTP_PROXY`/`HTTPS_PROXY` env vars), `"explicit-proxy"` (with `url`). Both modes accept an optional `tls` sub-object.
-  - `request.tls`: TLS override for direct connections. Fields: `ca`, `cert`, `key`, `passphrase` (all accept SecretRef), `serverName`, `insecureSkipVerify`.
-  - `request.allowPrivateNetwork`: when `true`, allow HTTPS to `baseUrl` when DNS resolves to private, CGNAT, or similar ranges, via the provider HTTP fetch guard (operator opt-in for trusted self-hosted OpenAI-compatible endpoints). WebSocket uses the same `request` for headers/TLS but not that fetch SSRF gate. Default `false`.
-- `models.providers.*.models`: explicit provider model catalog entries.
-- `models.providers.*.models.*.contextWindow`: native model context window metadata.
-- `models.providers.*.models.*.contextTokens`: optional runtime context cap. Use this when you want a smaller effective context budget than the model's native `contextWindow`.
-- `models.providers.*.models.*.compat.supportsDeveloperRole`: optional compatibility hint. For `api: "openai-completions"` with a non-empty non-native `baseUrl` (host not `api.openai.com`), OpenClaw forces this to `false` at runtime. Empty/omitted `baseUrl` keeps default OpenAI behavior.
-- `models.providers.*.models.*.compat.requiresStringContent`: optional compatibility hint for string-only OpenAI-compatible chat endpoints. When `true`, OpenClaw flattens pure text `messages[].content` arrays into plain strings before sending the request.
-- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock auto-discovery settings root.
-- `plugins.entries.amazon-bedrock.config.discovery.enabled`: turn implicit discovery on/off.
-- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS region for discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optional provider-id filter for targeted discovery.
-- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: polling interval for discovery refresh.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: fallback context window for discovered models.
-- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: fallback max output tokens for discovered models.
-
-### Provider examples
-
-<Accordion title="Cerebras (GLM 4.6 / 4.7)">
-
-```json5
-{
-  env: { CEREBRAS_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: {
-        primary: "cerebras/zai-glm-4.7",
-        fallbacks: ["cerebras/zai-glm-4.6"],
-      },
-      models: {
-        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
-        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
-      },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      cerebras: {
-        baseUrl: "https://api.cerebras.ai/v1",
-        apiKey: "${CEREBRAS_API_KEY}",
-        api: "openai-completions",
-        models: [
-          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
-          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
-        ],
-      },
-    },
-  },
-}
-```
-
-Use `cerebras/zai-glm-4.7` for Cerebras; `zai/glm-4.7` for Z.AI direct.
-
-</Accordion>
-
-<Accordion title="OpenCode">
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "opencode/claude-opus-4-6" },
-      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
-    },
-  },
-}
-```
-
-Set `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`). Use `opencode/...` refs for the Zen catalog or `opencode-go/...` refs for the Go catalog. Shortcut: `openclaw onboard --auth-choice opencode-zen` or `openclaw onboard --auth-choice opencode-go`.
-
-</Accordion>
-
-<Accordion title="Z.AI (GLM-4.7)">
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "zai/glm-4.7" },
-      models: { "zai/glm-4.7": {} },
-    },
-  },
-}
-```
-
-Set `ZAI_API_KEY`. `z.ai/*` and `z-ai/*` are accepted aliases. Shortcut: `openclaw onboard --auth-choice zai-api-key`.
-
-- General endpoint: `https://api.z.ai/api/paas/v4`
-- Coding endpoint (default): `https://api.z.ai/api/coding/paas/v4`
-- For the general endpoint, define a custom provider with the base URL override.
-
-</Accordion>
-
-<Accordion title="Moonshot AI (Kimi)">
-
-```json5
-{
-  env: { MOONSHOT_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: { primary: "moonshot/kimi-k2.6" },
-      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      moonshot: {
-        baseUrl: "https://api.moonshot.ai/v1",
-        apiKey: "${MOONSHOT_API_KEY}",
-        api: "openai-completions",
-        models: [
-          {
-            id: "kimi-k2.6",
-            name: "Kimi K2.6",
-            reasoning: false,
-            input: ["text", "image"],
-            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
-            contextWindow: 262144,
-            maxTokens: 262144,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-For the China endpoint: `baseUrl: "https://api.moonshot.cn/v1"` or `openclaw onboard --auth-choice moonshot-api-key-cn`.
-
-Native Moonshot endpoints advertise streaming usage compatibility on the shared
-`openai-completions` transport, and OpenClaw keys that off endpoint capabilities
-rather than the built-in provider id alone.
-
-</Accordion>
-
-<Accordion title="Kimi Coding">
-
-```json5
-{
-  env: { KIMI_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: { primary: "kimi/kimi-code" },
-      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
-    },
-  },
-}
-```
-
-Anthropic-compatible, built-in provider. Shortcut: `openclaw onboard --auth-choice kimi-code-api-key`.
-
-</Accordion>
-
-<Accordion title="Synthetic (Anthropic-compatible)">
-
-```json5
-{
-  env: { SYNTHETIC_API_KEY: "sk-..." },
-  agents: {
-    defaults: {
-      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
-      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      synthetic: {
-        baseUrl: "https://api.synthetic.new/anthropic",
-        apiKey: "${SYNTHETIC_API_KEY}",
-        api: "anthropic-messages",
-        models: [
-          {
-            id: "hf:MiniMaxAI/MiniMax-M2.5",
-            name: "MiniMax M2.5",
-            reasoning: true,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 192000,
-            maxTokens: 65536,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-Base URL should omit `/v1` (Anthropic client appends it). Shortcut: `openclaw onboard --auth-choice synthetic-api-key`.
-
-</Accordion>
-
-<Accordion title="MiniMax M2.7 (direct)">
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "minimax/MiniMax-M2.7" },
-      models: {
-        "minimax/MiniMax-M2.7": { alias: "Minimax" },
-      },
-    },
-  },
-  models: {
-    mode: "merge",
-    providers: {
-      minimax: {
-        baseUrl: "https://api.minimax.io/anthropic",
-        apiKey: "${MINIMAX_API_KEY}",
-        api: "anthropic-messages",
-        models: [
-          {
-            id: "MiniMax-M2.7",
-            name: "MiniMax M2.7",
-            reasoning: true,
-            input: ["text", "image"],
-            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
-            contextWindow: 204800,
-            maxTokens: 131072,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-Set `MINIMAX_API_KEY`. Shortcuts:
-`openclaw onboard --auth-choice minimax-global-api` or
-`openclaw onboard --auth-choice minimax-cn-api`.
-The model catalog defaults to M2.7 only.
-On the Anthropic-compatible streaming path, OpenClaw disables MiniMax thinking
-by default unless you explicitly set `thinking` yourself. `/fast on` or
-`params.fastMode: true` rewrites `MiniMax-M2.7` to
-`MiniMax-M2.7-highspeed`.
-
-</Accordion>
-
-<Accordion title="Local models (LM Studio)">
-
-See [Local Models](/gateway/local-models). TL;DR: run a large local model via LM Studio Responses API on serious hardware; keep hosted models merged for fallback.
-
-</Accordion>
-
----
+Tool policy, experimental toggles, provider-backed tool config, and custom
+provider / base-URL setup moved to a dedicated page — see
+[Configuration — tools and custom providers](/gateway/config-tools).
 
 ## Skills
 
@@ -1577,7 +936,7 @@ Metadata written by CLI guided setup flows (`onboard`, `configure`, `doctor`):
 
 ## Identity
 
-See `agents.list` identity fields under [Agent defaults](#agent-defaults).
+See `agents.list` identity fields under [Agent defaults](/gateway/config-agents#agent-defaults).
 
 ---
 

docs/gateway/configuration.md

@@ -151,7 +151,7 @@ is skipped when a candidate contains redacted secret placeholders such as `***`.
     - Model refs use `provider/model` format (e.g. `anthropic/claude-opus-4-6`).
     - `agents.defaults.imageMaxDimensionPx` controls transcript/tool image downscaling (default `1200`); lower values usually reduce vision-token usage on screenshot-heavy runs.
     - See [Models CLI](/concepts/models) for switching models in chat and [Model Failover](/concepts/model-failover) for auth rotation and fallback behavior.
-    - For custom/self-hosted providers, see [Custom providers](/gateway/configuration-reference#custom-providers-and-base-urls) in the reference.
+    - For custom/self-hosted providers, see [Custom providers](/gateway/config-tools#custom-providers-and-base-urls) in the reference.
 
   </Accordion>
 

docs/gateway/logging.md

@@ -111,3 +111,8 @@ Behavior:
 - **WhatsApp message bodies** are logged at `debug` (use `--verbose` to see them)
 
 This keeps existing file logs stable while making interactive output scannable.
+
+## Related
+
+- [Logging overview](/logging)
+- [Diagnostics export](/gateway/diagnostics)

docs/gateway/openai-http-api.md

@@ -278,3 +278,8 @@ Notes:
 - `openclaw/default` is always present so one stable id works across environments.
 - Backend provider/model overrides belong in `x-openclaw-model`, not the OpenAI `model` field.
 - `/v1/embeddings` supports `input` as a string or array of strings.
+
+## Related
+
+- [Configuration reference](/gateway/configuration-reference)
+- [OpenAI](/providers/openai)

docs/gateway/openresponses-http-api.md

@@ -338,3 +338,8 @@ curl -N http://127.0.0.1:18789/v1/responses \
     "input": "hi"
   }'
 ```
+
+## Related
+
+- [OpenAI chat completions](/gateway/openai-http-api)
+- [OpenAI](/providers/openai)

docs/gateway/remote-gateway-readme.md

@@ -162,3 +162,8 @@ launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel
 | `RunAtLoad`                          | Starts tunnel when the agent loads                           |
 
 OpenClaw.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
+
+## Related
+
+- [Remote access](/gateway/remote)
+- [Tailscale](/gateway/tailscale)

docs/gateway/tools-invoke-http-api.md

@@ -159,3 +159,8 @@ curl -sS http://127.0.0.1:18789/tools/invoke \
     "args": {}
   }'
 ```
+
+## Related
+
+- [Gateway protocol](/gateway/protocol)
+- [Tools and plugins](/tools)

docs/gateway/troubleshooting.md

@@ -57,7 +57,7 @@ Related:
 
 - [/providers/anthropic](/providers/anthropic)
 - [/reference/token-use](/reference/token-use)
-- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
+- [/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
 
 ## Local OpenAI-compatible backend passes direct probes but agent runs fail
 

docs/help/debugging.md

@@ -321,3 +321,8 @@ Default file:
 - Raw stream logs can include full prompts, tool output, and user data.
 - Keep logs local and delete them after debugging.
 - If you share logs, scrub secrets and PII first.
+
+## Related
+
+- [Troubleshooting](/help/troubleshooting)
+- [FAQ](/help/faq)

docs/help/faq-first-run.md

@@ -0,0 +1,865 @@
+---
+summary: "FAQ: quick-start and first-run setup — install, onboard, auth, subscriptions, initial failures"
+read_when:
+  - New install, onboarding stuck, or first-run errors
+  - Choosing auth and provider subscriptions
+  - Cannot access docs.openclaw.ai, cannot open dashboard, install stuck
+title: "FAQ: first-run setup"
+sidebarTitle: "First-run FAQ"
+---
+
+Quick-start and first-run Q&A. For everyday operations, models, auth, sessions,
+and troubleshooting see the main [FAQ](/help/faq).
+
+## Quick start and first-run setup
+
+<AccordionGroup>
+  <Accordion title="I am stuck, fastest way to get unstuck">
+    Use a local AI agent that can **see your machine**. That is far more effective than asking
+    in Discord, because most "I'm stuck" cases are **local config or environment issues** that
+    remote helpers cannot inspect.
+
+    - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
+    - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
+
+    These tools can read the repo, run commands, inspect logs, and help fix your machine-level
+    setup (PATH, services, permissions, auth files). Give them the **full source checkout** via
+    the hackable (git) install:
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+
+    This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and
+    reason about the exact version you are running. You can always switch back to stable later
+    by re-running the installer without `--install-method git`.
+
+    Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the
+    necessary commands. That keeps changes small and easier to audit.
+
+    If you discover a real bug or fix, please file a GitHub issue or send a PR:
+    [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
+    [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
+
+    Start with these commands (share outputs when asking for help):
+
+    ```bash
+    openclaw status
+    openclaw models status
+    openclaw doctor
+    ```
+
+    What they do:
+
+    - `openclaw status`: quick snapshot of gateway/agent health + basic config.
+    - `openclaw models status`: checks provider auth + model availability.
+    - `openclaw doctor`: validates and repairs common config/state issues.
+
+    Other useful CLI checks: `openclaw status --all`, `openclaw logs --follow`,
+    `openclaw gateway status`, `openclaw health --verbose`.
+
+    Quick debug loop: [First 60 seconds if something is broken](#first-60-seconds-if-something-is-broken).
+    Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).
+
+  </Accordion>
+
+  <Accordion title="Heartbeat keeps skipping. What do the skip reasons mean?">
+    Common heartbeat skip reasons:
+
+    - `quiet-hours`: outside the configured active-hours window
+    - `empty-heartbeat-file`: `HEARTBEAT.md` exists but only contains blank/header-only scaffolding
+    - `no-tasks-due`: `HEARTBEAT.md` task mode is active but none of the task intervals are due yet
+    - `alerts-disabled`: all heartbeat visibility is disabled (`showOk`, `showAlerts`, and `useIndicator` are all off)
+
+    In task mode, due timestamps are only advanced after a real heartbeat run
+    completes. Skipped runs do not mark tasks as completed.
+
+    Docs: [Heartbeat](/gateway/heartbeat), [Automation & Tasks](/automation).
+
+  </Accordion>
+
+  <Accordion title="Recommended way to install and set up OpenClaw">
+    The repo recommends running from source and using onboarding:
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash
+    openclaw onboard --install-daemon
+    ```
+
+    The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.
+
+    From source (contributors/dev):
+
+    ```bash
+    git clone https://github.com/openclaw/openclaw.git
+    cd openclaw
+    pnpm install
+    pnpm build
+    pnpm ui:build
+    openclaw onboard
+    ```
+
+    If you don't have a global install yet, run it via `pnpm openclaw onboard`.
+
+  </Accordion>
+
+  <Accordion title="How do I open the dashboard after onboarding?">
+    The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine.
+  </Accordion>
+
+  <Accordion title="How do I authenticate the dashboard on localhost vs remote?">
+    **Localhost (same machine):**
+
+    - Open `http://127.0.0.1:18789/`.
+    - If it asks for shared-secret auth, paste the configured token or password into Control UI settings.
+    - Token source: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
+    - Password source: `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
+    - If no shared secret is configured yet, generate a token with `openclaw doctor --generate-gateway-token`.
+
+    **Not on localhost:**
+
+    - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https://<magicdns>/`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no pasted shared secret, assumes trusted gateway host); HTTP APIs still require shared-secret auth unless you deliberately use private-ingress `none` or trusted-proxy HTTP auth.
+      Bad concurrent Serve auth attempts from the same client are serialized before the failed-auth limiter records them, so the second bad retry can already show `retry later`.
+    - **Tailnet bind**: run `openclaw gateway --bind tailnet --token "<token>"` (or configure password auth), open `http://<tailscale-ip>:18789/`, then paste the matching shared secret in dashboard settings.
+    - **Identity-aware reverse proxy**: keep the Gateway behind a non-loopback trusted proxy, configure `gateway.auth.mode: "trusted-proxy"`, then open the proxy URL.
+    - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`. Shared-secret auth still applies over the tunnel; paste the configured token or password if prompted.
+
+    See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.
+
+  </Accordion>
+
+  <Accordion title="Why are there two exec approval configs for chat approvals?">
+    They control different layers:
+
+    - `approvals.exec`: forwards approval prompts to chat destinations
+    - `channels.<channel>.execApprovals`: makes that channel act as a native approval client for exec approvals
+
+    The host exec policy is still the real approval gate. Chat config only controls where approval
+    prompts appear and how people can answer them.
+
+    In most setups you do **not** need both:
+
+    - If the chat already supports commands and replies, same-chat `/approve` works through the shared path.
+    - If a supported native channel can infer approvers safely, OpenClaw now auto-enables DM-first native approvals when `channels.<channel>.execApprovals.enabled` is unset or `"auto"`.
+    - When native approval cards/buttons are available, that native UI is the primary path; the agent should only include a manual `/approve` command if the tool result says chat approvals are unavailable or manual approval is the only path.
+    - Use `approvals.exec` only when prompts must also be forwarded to other chats or explicit ops rooms.
+    - Use `channels.<channel>.execApprovals.target: "channel"` or `"both"` only when you explicitly want approval prompts posted back into the originating room/topic.
+    - Plugin approvals are separate again: they use same-chat `/approve` by default, optional `approvals.plugin` forwarding, and only some native channels keep plugin-approval-native handling on top.
+
+    Short version: forwarding is for routing, native client config is for richer channel-specific UX.
+    See [Exec Approvals](/tools/exec-approvals).
+
+  </Accordion>
+
+  <Accordion title="What runtime do I need?">
+    Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.
+  </Accordion>
+
+  <Accordion title="Does it run on Raspberry Pi?">
+    Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**
+    disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.
+
+    If you want extra headroom (logs, media, other services), **2GB is recommended**, but it's
+    not a hard minimum.
+
+    Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for
+    local screen/camera/canvas or command execution. See [Nodes](/nodes).
+
+  </Accordion>
+
+  <Accordion title="Any tips for Raspberry Pi installs?">
+    Short version: it works, but expect rough edges.
+
+    - Use a **64-bit** OS and keep Node >= 22.
+    - Prefer the **hackable (git) install** so you can see logs and update fast.
+    - Start without channels/skills, then add them one by one.
+    - If you hit weird binary issues, it is usually an **ARM compatibility** problem.
+
+    Docs: [Linux](/platforms/linux), [Install](/install).
+
+  </Accordion>
+
+  <Accordion title="It is stuck on wake up my friend / onboarding will not hatch. What now?">
+    That screen depends on the Gateway being reachable and authenticated. The TUI also sends
+    "Wake up, my friend!" automatically on first hatch. If you see that line with **no reply**
+    and tokens stay at 0, the agent never ran.
+
+    1. Restart the Gateway:
+
+    ```bash
+    openclaw gateway restart
+    ```
+
+    2. Check status + auth:
+
+    ```bash
+    openclaw status
+    openclaw models status
+    openclaw logs --follow
+    ```
+
+    3. If it still hangs, run:
+
+    ```bash
+    openclaw doctor
+    ```
+
+    If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI
+    is pointed at the right Gateway. See [Remote access](/gateway/remote).
+
+  </Accordion>
+
+  <Accordion title="Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?">
+    Yes. Copy the **state directory** and **workspace**, then run Doctor once. This
+    keeps your bot "exactly the same" (memory, session history, auth, and channel
+    state) as long as you copy **both** locations:
+
+    1. Install OpenClaw on the new machine.
+    2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.
+    3. Copy your workspace (default: `~/.openclaw/workspace`).
+    4. Run `openclaw doctor` and restart the Gateway service.
+
+    That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in
+    remote mode, remember the gateway host owns the session store and workspace.
+
+    **Important:** if you only commit/push your workspace to GitHub, you're backing
+    up **memory + bootstrap files**, but **not** session history or auth. Those live
+    under `~/.openclaw/` (for example `~/.openclaw/agents/<agentId>/sessions/`).
+
+    Related: [Migrating](/install/migrating), [Where things live on disk](#where-things-live-on-disk),
+    [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),
+    [Remote mode](/gateway/remote).
+
+  </Accordion>
+
+  <Accordion title="Where do I see what is new in the latest version?">
+    Check the GitHub changelog:
+    [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
+
+    Newest entries are at the top. If the top section is marked **Unreleased**, the next dated
+    section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and
+    **Fixes** (plus docs/other sections when needed).
+
+  </Accordion>
+
+  <Accordion title="Cannot access docs.openclaw.ai (SSL error)">
+    Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
+    Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry.
+    Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
+
+    If you still can't reach the site, the docs are mirrored on GitHub:
+    [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
+
+  </Accordion>
+
+  <Accordion title="Difference between stable and beta">
+    **Stable** and **beta** are **npm dist-tags**, not separate code lines:
+
+    - `latest` = stable
+    - `beta` = early build for testing
+
+    Usually, a stable release lands on **beta** first, then an explicit
+    promotion step moves that same version to `latest`. Maintainers can also
+    publish straight to `latest` when needed. That's why beta and stable can
+    point at the **same version** after promotion.
+
+    See what changed:
+    [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
+
+    For install one-liners and the difference between beta and dev, see the accordion below.
+
+  </Accordion>
+
+  <Accordion title="How do I install the beta version and what is the difference between beta and dev?">
+    **Beta** is the npm dist-tag `beta` (may match `latest` after promotion).
+    **Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.
+
+    One-liners (macOS/Linux):
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta
+    ```
+
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+
+    Windows installer (PowerShell):
+    [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
+
+    More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).
+
+  </Accordion>
+
+  <Accordion title="How do I try the latest bits?">
+    Two options:
+
+    1. **Dev channel (git checkout):**
+
+    ```bash
+    openclaw update --channel dev
+    ```
+
+    This switches to the `main` branch and updates from source.
+
+    2. **Hackable install (from the installer site):**
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+
+    That gives you a local repo you can edit, then update via git.
+
+    If you prefer a clean clone manually, use:
+
+    ```bash
+    git clone https://github.com/openclaw/openclaw.git
+    cd openclaw
+    pnpm install
+    pnpm build
+    ```
+
+    Docs: [Update](/cli/update), [Development channels](/install/development-channels),
+    [Install](/install).
+
+  </Accordion>
+
+  <Accordion title="How long does install and onboarding usually take?">
+    Rough guide:
+
+    - **Install:** 2-5 minutes
+    - **Onboarding:** 5-15 minutes depending on how many channels/models you configure
+
+    If it hangs, use [Installer stuck](#quick-start-and-first-run-setup)
+    and the fast debug loop in [I am stuck](#quick-start-and-first-run-setup).
+
+  </Accordion>
+
+  <Accordion title="Installer stuck? How do I get more feedback?">
+    Re-run the installer with **verbose output**:
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
+    ```
+
+    Beta install with verbose:
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
+    ```
+
+    For a hackable (git) install:
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
+    ```
+
+    Windows (PowerShell) equivalent:
+
+    ```powershell
+    # install.ps1 has no dedicated -Verbose flag yet.
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+
+    More options: [Installer flags](/install/installer).
+
+  </Accordion>
+
+  <Accordion title="Windows install says git not found or openclaw not recognized">
+    Two common Windows issues:
+
+    **1) npm error spawn git / git not found**
+
+    - Install **Git for Windows** and make sure `git` is on your PATH.
+    - Close and reopen PowerShell, then re-run the installer.
+
+    **2) openclaw is not recognized after install**
+
+    - Your npm global bin folder is not on PATH.
+    - Check the path:
+
+      ```powershell
+      npm config get prefix
+      ```
+
+    - Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`).
+    - Close and reopen PowerShell after updating PATH.
+
+    If you want the smoothest Windows setup, use **WSL2** instead of native Windows.
+    Docs: [Windows](/platforms/windows).
+
+  </Accordion>
+
+  <Accordion title="Windows exec output shows garbled Chinese text - what should I do?">
+    This is usually a console code page mismatch on native Windows shells.
+
+    Symptoms:
+
+    - `system.run`/`exec` output renders Chinese as mojibake
+    - The same command looks fine in another terminal profile
+
+    Quick workaround in PowerShell:
+
+    ```powershell
+    chcp 65001
+    [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+    [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+    $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+    ```
+
+    Then restart the Gateway and retry your command:
+
+    ```powershell
+    openclaw gateway restart
+    ```
+
+    If you still reproduce this on latest OpenClaw, track/report it in:
+
+    - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640)
+
+  </Accordion>
+
+  <Accordion title="The docs did not answer my question - how do I get a better answer?">
+    Use the **hackable (git) install** so you have the full source and docs locally, then ask
+    your bot (or Claude/Codex) _from that folder_ so it can read the repo and answer precisely.
+
+    ```bash
+    curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+
+    More detail: [Install](/install) and [Installer flags](/install/installer).
+
+  </Accordion>
+
+  <Accordion title="How do I install OpenClaw on Linux?">
+    Short answer: follow the Linux guide, then run onboarding.
+
+    - Linux quick path + service install: [Linux](/platforms/linux).
+    - Full walkthrough: [Getting Started](/start/getting-started).
+    - Installer + updates: [Install & updates](/install/updating).
+
+  </Accordion>
+
+  <Accordion title="How do I install OpenClaw on a VPS?">
+    Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
+
+    Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
+    Remote access: [Gateway remote](/gateway/remote).
+
+  </Accordion>
+
+  <Accordion title="Where are the cloud/VPS install guides?">
+    We keep a **hosting hub** with the common providers. Pick one and follow the guide:
+
+    - [VPS hosting](/vps) (all providers in one place)
+    - [Fly.io](/install/fly)
+    - [Hetzner](/install/hetzner)
+    - [exe.dev](/install/exe-dev)
+
+    How it works in the cloud: the **Gateway runs on the server**, and you access it
+    from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace
+    live on the server, so treat the host as the source of truth and back it up.
+
+    You can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access
+    local screen/camera/canvas or run commands on your laptop while keeping the
+    Gateway in the cloud.
+
+    Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).
+    Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
+
+  </Accordion>
+
+  <Accordion title="Can I ask OpenClaw to update itself?">
+    Short answer: **possible, not recommended**. The update flow can restart the
+    Gateway (which drops the active session), may need a clean git checkout, and
+    can prompt for confirmation. Safer: run updates from a shell as the operator.
+
+    Use the CLI:
+
+    ```bash
+    openclaw update
+    openclaw update status
+    openclaw update --channel stable|beta|dev
+    openclaw update --tag <dist-tag|version>
+    openclaw update --no-restart
+    ```
+
+    If you must automate from an agent:
+
+    ```bash
+    openclaw update --yes --no-restart
+    openclaw gateway restart
+    ```
+
+    Docs: [Update](/cli/update), [Updating](/install/updating).
+
+  </Accordion>
+
+  <Accordion title="What does onboarding actually do?">
+    `openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
+
+    - **Model/auth setup** (provider OAuth, API keys, Anthropic setup-token, plus local model options such as LM Studio)
+    - **Workspace** location + bootstrap files
+    - **Gateway settings** (bind/port/auth/tailscale)
+    - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, plus bundled channel plugins like QQ Bot)
+    - **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
+    - **Health checks** and **skills** selection
+
+    It also warns if your configured model is unknown or missing auth.
+
+  </Accordion>
+
+  <Accordion title="Do I need a Claude or OpenAI subscription to run this?">
+    No. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with
+    **local-only models** so your data stays on your device. Subscriptions (Claude
+    Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
+
+    For Anthropic in OpenClaw, the practical split is:
+
+    - **Anthropic API key**: normal Anthropic API billing
+    - **Claude CLI / Claude subscription auth in OpenClaw**: Anthropic staff
+      told us this usage is allowed again, and OpenClaw is treating `claude -p`
+      usage as sanctioned for this integration unless Anthropic publishes a new
+      policy
+
+    For long-lived gateway hosts, Anthropic API keys are still the more
+    predictable setup. OpenAI Codex OAuth is explicitly supported for external
+    tools like OpenClaw.
+
+    OpenClaw also supports other hosted subscription-style options including
+    **Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, and
+    **Z.AI / GLM Coding Plan**.
+
+    Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
+    [Qwen Cloud](/providers/qwen),
+    [MiniMax](/providers/minimax), [GLM Models](/providers/glm),
+    [Local models](/gateway/local-models), [Models](/concepts/models).
+
+  </Accordion>
+
+  <Accordion title="Can I use Claude Max subscription without an API key?">
+    Yes.
+
+    Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so
+    OpenClaw treats Claude subscription auth and `claude -p` usage as sanctioned
+    for this integration unless Anthropic publishes a new policy. If you want
+    the most predictable server-side setup, use an Anthropic API key instead.
+
+  </Accordion>
+
+  <Accordion title="Do you support Claude subscription auth (Claude Pro or Max)?">
+    Yes.
+
+    Anthropic staff told us this usage is allowed again, so OpenClaw treats
+    Claude CLI reuse and `claude -p` usage as sanctioned for this integration
+    unless Anthropic publishes a new policy.
+
+    Anthropic setup-token is still available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
+    For production or multi-user workloads, Anthropic API key auth is still the
+    safer, more predictable choice. If you want other subscription-style hosted
+    options in OpenClaw, see [OpenAI](/providers/openai), [Qwen / Model
+    Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [GLM
+    Models](/providers/glm).
+
+  </Accordion>
+
+</AccordionGroup>
+
+<a id="why-am-i-seeing-http-429-ratelimiterror-from-anthropic"></a>
+
+<AccordionGroup>
+  <Accordion title="Why am I seeing HTTP 429 rate_limit_error from Anthropic?">
+    That means your **Anthropic quota/rate limit** is exhausted for the current window. If you
+    use **Claude CLI**, wait for the window to reset or upgrade your plan. If you
+    use an **Anthropic API key**, check the Anthropic Console
+    for usage/billing and raise limits as needed.
+
+    If the message is specifically:
+    `Extra usage is required for long context requests`, the request is trying to use
+    Anthropic's 1M context beta (`context1m: true`). That only works when your
+    credential is eligible for long-context billing (API key billing or the
+    OpenClaw Claude-login path with Extra Usage enabled).
+
+    Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.
+    See [Models](/cli/models), [OAuth](/concepts/oauth), and
+    [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
+
+  </Accordion>
+
+  <Accordion title="Is AWS Bedrock supported?">
+    Yes. OpenClaw has a bundled **Amazon Bedrock (Converse)** provider. With AWS env markers present, OpenClaw can auto-discover the streaming/text Bedrock catalog and merge it as an implicit `amazon-bedrock` provider; otherwise you can explicitly enable `plugins.entries.amazon-bedrock.config.discovery.enabled` or add a manual provider entry. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
+  </Accordion>
+
+  <Accordion title="How does Codex auth work?">
+    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 the provider and auth-profile id for ChatGPT/Codex OAuth.
+    It is also the explicit PI model prefix for Codex OAuth:
+
+    - `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 use
+    `openai-codex/*` model refs for PI runs.
+
+  </Accordion>
+
+  <Accordion title="Why can Codex OAuth limits differ from ChatGPT web?">
+    Codex OAuth uses OpenAI-managed, plan-dependent quota windows. In practice,
+    those limits can differ from the ChatGPT website/app experience, even when
+    both are tied to the same account.
+
+    OpenClaw can show the currently visible provider usage/quota windows in
+    `openclaw models status`, but it does not invent or normalize ChatGPT-web
+    entitlements into direct API access. If you want the direct OpenAI Platform
+    billing/limit path, use `openai/*` with an API key.
+
+  </Accordion>
+
+  <Accordion title="Do you support OpenAI subscription auth (Codex OAuth)?">
+    Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
+    OpenAI explicitly allows subscription OAuth usage in external tools/workflows
+    like OpenClaw. Onboarding can run the OAuth flow for you.
+
+    See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).
+
+  </Accordion>
+
+  <Accordion title="How do I set up Gemini CLI OAuth?">
+    Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.
+
+    Steps:
+
+    1. Install Gemini CLI locally so `gemini` is on `PATH`
+       - Homebrew: `brew install gemini-cli`
+       - npm: `npm install -g @google/gemini-cli`
+    2. Enable the plugin: `openclaw plugins enable google`
+    3. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
+    4. Default model after login: `google-gemini-cli/gemini-3-flash-preview`
+    5. If requests fail, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` on the gateway host
+
+    This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
+
+  </Accordion>
+
+  <Accordion title="Is a local model OK for casual chats?">
+    Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** model build you can locally (LM Studio) and see [/gateway/local-models](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/security).
+  </Accordion>
+
+  <Accordion title="How do I keep hosted model traffic in a specific region?">
+    Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select.
+  </Accordion>
+
+  <Accordion title="Do I have to buy a Mac Mini to install this?">
+    No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people
+    buy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too.
+
+    You only need a Mac **for macOS-only tools**. For iMessage, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node.
+
+    Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).
+
+  </Accordion>
+
+  <Accordion title="Do I need a Mac mini for iMessage support?">
+    You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini -
+    any Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.
+
+    Common setups:
+
+    - Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages.
+    - Run everything on the Mac if you want the simplest single-machine setup.
+
+    Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes),
+    [Mac remote mode](/platforms/mac/remote).
+
+  </Accordion>
+
+  <Accordion title="If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?">
+    Yes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a
+    **node** (companion device). Nodes don't run the Gateway - they provide extra
+    capabilities like screen/camera/canvas and `system.run` on that device.
+
+    Common pattern:
+
+    - Gateway on the Mac mini (always-on).
+    - MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
+    - Use `openclaw nodes status` / `openclaw nodes list` to see it.
+
+    Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
+
+  </Accordion>
+
+  <Accordion title="Can I use Bun?">
+    Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
+    Use **Node** for stable gateways.
+
+    If you still want to experiment with Bun, do it on a non-production gateway
+    without WhatsApp/Telegram.
+
+  </Accordion>
+
+  <Accordion title="Telegram: what goes in allowFrom?">
+    `channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username.
+
+    Setup asks for numeric user IDs only. If you already have legacy `@username` entries in config, `openclaw doctor --fix` can try to resolve them.
+
+    Safer (no third-party bot):
+
+    - DM your bot, then run `openclaw logs --follow` and read `from.id`.
+
+    Official Bot API:
+
+    - DM your bot, then call `https://api.telegram.org/bot<bot_token>/getUpdates` and read `message.from.id`.
+
+    Third-party (less private):
+
+    - DM `@userinfobot` or `@getidsbot`.
+
+    See [/channels/telegram](/channels/telegram#access-control-and-activation).
+
+  </Accordion>
+
+  <Accordion title="Can multiple people use one WhatsApp number with different OpenClaw instances?">
+    Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp).
+  </Accordion>
+
+  <Accordion title='Can I run a "fast chat" agent and an "Opus for coding" agent?'>
+    Yes. Use multi-agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration).
+  </Accordion>
+
+  <Accordion title="Does Homebrew work on Linux?">
+    Yes. Homebrew supports Linux (Linuxbrew). Quick setup:
+
+    ```bash
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
+    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+    brew install <formula>
+    ```
+
+    If you run OpenClaw via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non-login shells.
+    Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.
+
+  </Accordion>
+
+  <Accordion title="Difference between the hackable git install and npm install">
+    - **Hackable (git) install:** full source checkout, editable, best for contributors.
+      You run builds locally and can patch code/docs.
+    - **npm install:** global CLI install, no repo, best for "just run it."
+      Updates come from npm dist-tags.
+
+    Docs: [Getting started](/start/getting-started), [Updating](/install/updating).
+
+  </Accordion>
+
+  <Accordion title="Can I switch between npm and git installs later?">
+    Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
+    This **does not delete your data** - it only changes the OpenClaw code install. Your state
+    (`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched.
+
+    From npm to git:
+
+    ```bash
+    git clone https://github.com/openclaw/openclaw.git
+    cd openclaw
+    pnpm install
+    pnpm build
+    openclaw doctor
+    openclaw gateway restart
+    ```
+
+    From git to npm:
+
+    ```bash
+    npm install -g openclaw@latest
+    openclaw doctor
+    openclaw gateway restart
+    ```
+
+    Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
+
+    Backup tips: see [Backup strategy](#where-things-live-on-disk).
+
+  </Accordion>
+
+  <Accordion title="Should I run the Gateway on my laptop or a VPS?">
+    Short answer: **if you want 24/7 reliability, use a VPS**. If you want the
+    lowest friction and you're okay with sleep/restarts, run it locally.
+
+    **Laptop (local Gateway)**
+
+    - **Pros:** no server cost, direct access to local files, live browser window.
+    - **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
+
+    **VPS / cloud**
+
+    - **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.
+    - **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.
+
+    **OpenClaw-specific note:** WhatsApp/Telegram/Slack/Mattermost/Discord all work fine from a VPS. The only real trade-off is **headless browser** vs a visible window. See [Browser](/tools/browser).
+
+    **Recommended default:** VPS if you had gateway disconnects before. Local is great when you're actively using the Mac and want local file access or UI automation with a visible browser.
+
+  </Accordion>
+
+  <Accordion title="How important is it to run OpenClaw on a dedicated machine?">
+    Not required, but **recommended for reliability and isolation**.
+
+    - **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
+    - **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates.
+
+    If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes).
+    For security guidance, read [Security](/gateway/security).
+
+  </Accordion>
+
+  <Accordion title="What are the minimum VPS requirements and recommended OS?">
+    OpenClaw is lightweight. For a basic Gateway + one chat channel:
+
+    - **Absolute minimum:** 1 vCPU, 1GB RAM, ~500MB disk.
+    - **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.
+
+    OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there.
+
+    Docs: [Linux](/platforms/linux), [VPS hosting](/vps).
+
+  </Accordion>
+
+  <Accordion title="Can I run OpenClaw in a VM and what are the requirements?">
+    Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough
+    RAM for the Gateway and any channels you enable.
+
+    Baseline guidance:
+
+    - **Absolute minimum:** 1 vCPU, 1GB RAM.
+    - **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.
+    - **OS:** Ubuntu LTS or another modern Debian/Ubuntu.
+
+    If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling
+    compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
+    If you are running macOS in a VM, see [macOS VM](/install/macos-vm).
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [FAQ](/help/faq) — the main FAQ (models, sessions, gateway, security, more)
+- [Install overview](/install)
+- [Getting started](/start/getting-started)
+- [Troubleshooting](/help/troubleshooting)

docs/help/faq-models.md

@@ -0,0 +1,535 @@
+---
+summary: "FAQ: model defaults, selection, aliases, switching, failover, and auth profiles"
+read_when:
+  - Choosing or switching models, configuring aliases
+  - Debugging model failover / "All models failed"
+  - Understanding auth profiles and how to manage them
+title: "FAQ: models and auth"
+sidebarTitle: "Models FAQ"
+---
+
+Model- and auth-profile Q&A. For setup, sessions, gateway, channels, and
+troubleshooting, see the main [FAQ](/help/faq).
+
+## Models: defaults, selection, aliases, switching
+
+<AccordionGroup>
+  <Accordion title='What is the "default model"?'>
+    OpenClaw's default model is whatever you set as:
+
+    ```
+    agents.defaults.model.primary
+    ```
+
+    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>
+
+  <Accordion title="What model do you recommend?">
+    **Recommended default:** use the strongest latest-generation model available in your provider stack.
+    **For tool-enabled or untrusted-input agents:** prioritize model strength over cost.
+    **For routine/low-stakes chat:** use cheaper fallback models and route by agent role.
+
+    MiniMax has its own docs: [MiniMax](/providers/minimax) and
+    [Local models](/gateway/local-models).
+
+    Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper
+    model for routine chat or summaries. You can route models per agent and use sub-agents to
+    parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and
+    [Sub-agents](/tools/subagents).
+
+    Strong warning: weaker/over-quantized models are more vulnerable to prompt
+    injection and unsafe behavior. See [Security](/gateway/security).
+
+    More context: [Models](/concepts/models).
+
+  </Accordion>
+
+  <Accordion title="How do I switch models without wiping my config?">
+    Use **model commands** or edit only the **model** fields. Avoid full config replaces.
+
+    Safe options:
+
+    - `/model` in chat (quick, per-session)
+    - `openclaw models set ...` (updates just model config)
+    - `openclaw configure --section model` (interactive)
+    - edit `agents.defaults.model` in `~/.openclaw/openclaw.json`
+
+    Avoid `config.apply` with a partial object unless you intend to replace the whole config.
+    For RPC edits, inspect with `config.schema.lookup` first and prefer `config.patch`. The lookup payload gives you the normalized path, shallow schema docs/constraints, and immediate child summaries.
+    for partial updates.
+    If you did overwrite config, restore from backup or re-run `openclaw doctor` to repair.
+
+    Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor).
+
+  </Accordion>
+
+  <Accordion title="Can I use self-hosted models (llama.cpp, vLLM, Ollama)?">
+    Yes. Ollama is the easiest path for local models.
+
+    Quickest setup:
+
+    1. Install Ollama from `https://ollama.com/download`
+    2. Pull a local model such as `ollama pull gemma4`
+    3. If you want cloud models too, run `ollama signin`
+    4. Run `openclaw onboard` and choose `Ollama`
+    5. Pick `Local` or `Cloud + Local`
+
+    Notes:
+
+    - `Cloud + Local` gives you cloud models plus your local Ollama models
+    - cloud models such as `kimi-k2.5:cloud` do not need a local pull
+    - for manual switching, use `openclaw models list` and `openclaw models set ollama/<model>`
+
+    Security note: smaller or heavily quantized models are more vulnerable to prompt
+    injection. We strongly recommend **large models** for any bot that can use tools.
+    If you still want small models, enable sandboxing and strict tool allowlists.
+
+    Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models),
+    [Model providers](/concepts/model-providers), [Security](/gateway/security),
+    [Sandboxing](/gateway/sandboxing).
+
+  </Accordion>
+
+  <Accordion title="What do OpenClaw, Flawd, and Krill use for models?">
+    - These deployments can differ and may change over time; there is no fixed provider recommendation.
+    - Check the current runtime setting on each gateway with `openclaw models status`.
+    - For security-sensitive/tool-enabled agents, use the strongest latest-generation model available.
+  </Accordion>
+
+  <Accordion title="How do I switch models on the fly (without restarting)?">
+    Use the `/model` command as a standalone message:
+
+    ```
+    /model sonnet
+    /model opus
+    /model gpt
+    /model gpt-mini
+    /model gemini
+    /model gemini-flash
+    /model gemini-flash-lite
+    ```
+
+    These are the built-in aliases. Custom aliases can be added via `agents.defaults.models`.
+
+    You can list available models with `/model`, `/model list`, or `/model status`.
+
+    `/model` (and `/model list`) shows a compact, numbered picker. Select by number:
+
+    ```
+    /model 3
+    ```
+
+    You can also force a specific auth profile for the provider (per session):
+
+    ```
+    /model opus@anthropic:default
+    /model opus@anthropic:work
+    ```
+
+    Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.
+    It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
+
+    **How do I unpin a profile I set with @profile?**
+
+    Re-run `/model` **without** the `@profile` suffix:
+
+    ```
+    /model anthropic/claude-opus-4-6
+    ```
+
+    If you want to return to the default, pick it from `/model` (or send `/model <default provider/model>`).
+    Use `/model status` to confirm which auth profile is active.
+
+  </Accordion>
+
+  <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 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>
+
+  <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.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:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "openai/gpt-5.4": {
+              params: {
+                fastMode: true,
+              },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    For OpenAI, fast mode maps to `service_tier = "priority"` on supported native Responses requests. Session `/fast` overrides beat config defaults.
+
+    See [Thinking and fast mode](/tools/thinking) and [OpenAI fast mode](/providers/openai#fast-mode).
+
+  </Accordion>
+
+  <Accordion title='Why do I see "Model ... is not allowed" and then no reply?'>
+    If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any
+    session overrides. Choosing a model that isn't in that list returns:
+
+    ```
+    Model "provider/model" is not allowed. Use /model to list available models.
+    ```
+
+    That error is returned **instead of** a normal reply. Fix: add the model to
+    `agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.
+
+  </Accordion>
+
+  <Accordion title='Why do I see "Unknown model: minimax/MiniMax-M2.7"?'>
+    This means the **provider isn't configured** (no MiniMax provider config or auth
+    profile was found), so the model can't be resolved.
+
+    Fix checklist:
+
+    1. Upgrade to a current OpenClaw release (or run from source `main`), then restart the gateway.
+    2. Make sure MiniMax is configured (wizard or JSON), or that MiniMax auth
+       exists in env/auth profiles so the matching provider can be injected
+       (`MINIMAX_API_KEY` for `minimax`, `MINIMAX_OAUTH_TOKEN` or stored MiniMax
+       OAuth for `minimax-portal`).
+    3. Use the exact model id (case-sensitive) for your auth path:
+       `minimax/MiniMax-M2.7` or `minimax/MiniMax-M2.7-highspeed` for API-key
+       setup, or `minimax-portal/MiniMax-M2.7` /
+       `minimax-portal/MiniMax-M2.7-highspeed` for OAuth setup.
+    4. Run:
+
+       ```bash
+       openclaw models list
+       ```
+
+       and pick from the list (or `/model list` in chat).
+
+    See [MiniMax](/providers/minimax) and [Models](/concepts/models).
+
+  </Accordion>
+
+  <Accordion title="Can I use MiniMax as my default and OpenAI for complex tasks?">
+    Yes. Use **MiniMax as the default** and switch models **per session** when needed.
+    Fallbacks are for **errors**, not "hard tasks," so use `/model` or a separate agent.
+
+    **Option A: switch per session**
+
+    ```json5
+    {
+      env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
+      agents: {
+        defaults: {
+          model: { primary: "minimax/MiniMax-M2.7" },
+          models: {
+            "minimax/MiniMax-M2.7": { alias: "minimax" },
+            "openai/gpt-5.4": { alias: "gpt" },
+          },
+        },
+      },
+    }
+    ```
+
+    Then:
+
+    ```
+    /model gpt
+    ```
+
+    **Option B: separate agents**
+
+    - Agent A default: MiniMax
+    - Agent B default: OpenAI
+    - Route by agent or use `/agent` to switch
+
+    Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).
+
+  </Accordion>
+
+  <Accordion title="Are opus / sonnet / gpt built-in shortcuts?">
+    Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
+
+    - `opus` → `anthropic/claude-opus-4-6`
+    - `sonnet` → `anthropic/claude-sonnet-4-6`
+    - `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`
+    - `gemini-flash` → `google/gemini-3-flash-preview`
+    - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
+
+    If you set your own alias with the same name, your value wins.
+
+  </Accordion>
+
+  <Accordion title="How do I define/override model shortcuts (aliases)?">
+    Aliases come from `agents.defaults.models.<modelId>.alias`. Example:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "anthropic/claude-opus-4-6" },
+          models: {
+            "anthropic/claude-opus-4-6": { alias: "opus" },
+            "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
+            "anthropic/claude-haiku-4-5": { alias: "haiku" },
+          },
+        },
+      },
+    }
+    ```
+
+    Then `/model sonnet` (or `/<alias>` when supported) resolves to that model ID.
+
+  </Accordion>
+
+  <Accordion title="How do I add models from other providers like OpenRouter or Z.AI?">
+    OpenRouter (pay-per-token; many models):
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
+          models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
+        },
+      },
+      env: { OPENROUTER_API_KEY: "sk-or-..." },
+    }
+    ```
+
+    Z.AI (GLM models):
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "zai/glm-5" },
+          models: { "zai/glm-5": {} },
+        },
+      },
+      env: { ZAI_API_KEY: "..." },
+    }
+    ```
+
+    If you reference a provider/model but the required provider key is missing, you'll get a runtime auth error (e.g. `No API key found for provider "zai"`).
+
+    **No API key found for provider after adding a new agent**
+
+    This usually means the **new agent** has an empty auth store. Auth is per-agent and
+    stored in:
+
+    ```
+    ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
+    ```
+
+    Fix options:
+
+    - Run `openclaw agents add <id>` and configure auth during the wizard.
+    - Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`.
+
+    Do **not** reuse `agentDir` across agents; it causes auth/session collisions.
+
+  </Accordion>
+</AccordionGroup>
+
+## Model failover and "All models failed"
+
+<AccordionGroup>
+  <Accordion title="How does failover work?">
+    Failover happens in two stages:
+
+    1. **Auth profile rotation** within the same provider.
+    2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.
+
+    Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing.
+
+    The rate-limit bucket includes more than plain `429` responses. OpenClaw
+    also treats messages like `Too many concurrent requests`,
+    `ThrottlingException`, `concurrency limit reached`,
+    `workers_ai ... quota limit exceeded`, `resource exhausted`, and periodic
+    usage-window limits (`weekly/monthly limit reached`) as failover-worthy
+    rate limits.
+
+    Some billing-looking responses are not `402`, and some HTTP `402`
+    responses also stay in that transient bucket. If a provider returns
+    explicit billing text on `401` or `403`, OpenClaw can still keep that in
+    the billing lane, but provider-specific text matchers stay scoped to the
+    provider that owns them (for example OpenRouter `Key limit exceeded`). If a `402`
+    message instead looks like a retryable usage-window or
+    organization/workspace spend limit (`daily limit reached, resets tomorrow`,
+    `organization spending limit exceeded`), OpenClaw treats it as
+    `rate_limit`, not a long billing disable.
+
+    Context-overflow errors are different: signatures such as
+    `request_too_large`, `input exceeds the maximum number of tokens`,
+    `input token count exceeds the maximum number of input tokens`,
+    `input is too long for the model`, or `ollama error: context length
+    exceeded` stay on the compaction/retry path instead of advancing model
+    fallback.
+
+    Generic server-error text is intentionally narrower than "anything with
+    unknown/error in it". OpenClaw does treat provider-scoped transient shapes
+    such as Anthropic bare `An unknown error occurred`, OpenRouter bare
+    `Provider returned error`, stop-reason errors like `Unhandled stop reason:
+    error`, JSON `api_error` payloads with transient server text
+    (`internal server error`, `unknown error, 520`, `upstream error`, `backend
+    error`), and provider-busy errors such as `ModelNotReadyException` as
+    failover-worthy timeout/overloaded signals when the provider context
+    matches.
+    Generic internal fallback text like `LLM request failed with an unknown
+    error.` stays conservative and does not trigger model fallback by itself.
+
+  </Accordion>
+
+  <Accordion title='What does "No credentials found for profile anthropic:default" mean?'>
+    It means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store.
+
+    **Fix checklist:**
+
+    - **Confirm where auth profiles live** (new vs legacy paths)
+      - Current: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
+      - Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`)
+    - **Confirm your env var is loaded by the Gateway**
+      - If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.openclaw/.env` or enable `env.shellEnv`.
+    - **Make sure you're editing the correct agent**
+      - Multi-agent setups mean there can be multiple `auth-profiles.json` files.
+    - **Sanity-check model/auth status**
+      - Use `openclaw models status` to see configured models and whether providers are authenticated.
+
+    **Fix checklist for "No credentials found for profile anthropic"**
+
+    This means the run is pinned to an Anthropic auth profile, but the Gateway
+    can't find it in its auth store.
+
+    - **Use Claude CLI**
+      - Run `openclaw models auth login --provider anthropic --method cli --set-default` on the gateway host.
+    - **If you want to use an API key instead**
+      - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.
+      - Clear any pinned order that forces a missing profile:
+
+        ```bash
+        openclaw models auth order clear --provider anthropic
+        ```
+
+    - **Confirm you're running commands on the gateway host**
+      - In remote mode, auth profiles live on the gateway machine, not your laptop.
+
+  </Accordion>
+
+  <Accordion title="Why did it also try Google Gemini and fail?">
+    If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven't configured Google credentials, you'll see `No API key found for provider "google"`.
+
+    Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there.
+
+    **LLM request rejected: thinking signature required (Google Antigravity)**
+
+    Cause: the session history contains **thinking blocks without signatures** (often from
+    an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
+
+    Fix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a **new session** or set `/thinking off` for that agent.
+
+  </Accordion>
+</AccordionGroup>
+
+## Auth profiles: what they are and how to manage them
+
+Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns)
+
+<AccordionGroup>
+  <Accordion title="What is an auth profile?">
+    An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:
+
+    ```
+    ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
+    ```
+
+  </Accordion>
+
+  <Accordion title="What are typical profile IDs?">
+    OpenClaw uses provider-prefixed IDs like:
+
+    - `anthropic:default` (common when no email identity exists)
+    - `anthropic:<email>` for OAuth identities
+    - custom IDs you choose (e.g. `anthropic:work`)
+
+  </Accordion>
+
+  <Accordion title="Can I control which auth profile is tried first?">
+    Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.<provider>`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.
+
+    OpenClaw may temporarily skip a profile if it's in a short **cooldown** (rate limits/timeouts/auth failures) or a longer **disabled** state (billing/insufficient credits). To inspect this, run `openclaw models status --json` and check `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`.
+
+    Rate-limit cooldowns can be model-scoped. A profile that is cooling down
+    for one model can still be usable for a sibling model on the same provider,
+    while billing/disabled windows still block the whole profile.
+
+    You can also set a **per-agent** order override (stored in that agent's `auth-state.json`) via the CLI:
+
+    ```bash
+    # Defaults to the configured default agent (omit --agent)
+    openclaw models auth order get --provider anthropic
+
+    # Lock rotation to a single profile (only try this one)
+    openclaw models auth order set --provider anthropic anthropic:default
+
+    # Or set an explicit order (fallback within provider)
+    openclaw models auth order set --provider anthropic anthropic:work anthropic:default
+
+    # Clear override (fall back to config auth.order / round-robin)
+    openclaw models auth order clear --provider anthropic
+    ```
+
+    To target a specific agent:
+
+    ```bash
+    openclaw models auth order set --provider anthropic --agent main anthropic:default
+    ```
+
+    To verify what will actually be tried, use:
+
+    ```bash
+    openclaw models status --probe
+    ```
+
+    If a stored profile is omitted from the explicit order, probe reports
+    `excluded_by_auth_order` for that profile instead of trying it silently.
+
+  </Accordion>
+
+  <Accordion title="OAuth vs API key - what is the difference?">
+    OpenClaw supports both:
+
+    - **OAuth** often leverages subscription access (where applicable).
+    - **API keys** use pay-per-token billing.
+
+    The wizard explicitly supports Anthropic Claude CLI, OpenAI Codex OAuth, and API keys.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [FAQ](/help/faq) — the main FAQ
+- [FAQ — quick start and first-run setup](/help/faq-first-run)
+- [Model selection](/concepts/model-providers)
+- [Model failover](/concepts/model-failover)

docs/help/gpt54-codex-agentic-parity-maintainers.md

@@ -168,3 +168,7 @@ The parity harness is not the only evidence source. Keep this split explicit in
 | `/elevated full` hints were sometimes misleading            | PR B ties guidance to actual runtime capability and blocked reasons                     |
 | Long tasks could disappear into replay/compaction ambiguity | PR C emits explicit paused, blocked, abandoned, and replay-invalid state                |
 | Parity claims were anecdotal                                | PR D produces a report plus JSON verdict with the same scenario coverage on both models |
+
+## Related
+
+- [GPT-5.4 / Codex agentic parity](/help/gpt54-codex-agentic-parity)

docs/help/gpt54-codex-agentic-parity.md

@@ -226,3 +226,7 @@ Keep the default contract when:
 - you want the existing looser behavior
 - you are not using GPT-5-family models
 - you are testing prompts rather than runtime enforcement
+
+## Related
+
+- [GPT-5.4 / Codex parity maintainer notes](/help/gpt54-codex-agentic-parity-maintainers)

docs/help/scripts.md

@@ -49,3 +49,8 @@ Examples:
 
 - Keep scripts focused and documented.
 - Add a short entry in the relevant doc (or create one if missing).
+
+## Related
+
+- [Testing](/help/testing)
+- [Testing live](/help/testing-live)

docs/help/testing-live.md

@@ -4,7 +4,8 @@ read_when:
   - Running live model matrix / CLI backend / ACP / media-provider smokes
   - Debugging live-test credential resolution
   - Adding a new provider-specific live test
-title: "Testing — live suites"
+title: "Testing: live suites"
+sidebarTitle: "Live tests"
 ---
 
 For quick start, QA runners, unit/integration suites, and Docker flows, see
@@ -47,10 +48,12 @@ Live tests are split into two layers so we can isolate failures:
   - `pnpm test:live` (or `OPENCLAW_LIVE_TEST=1` if invoking Vitest directly)
 - Set `OPENCLAW_LIVE_MODELS=modern` (or `all`, alias for modern) to actually run this suite; otherwise it skips to keep `pnpm test:live` focused on gateway smoke
 - 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=modern` to run the modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + 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.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (comma allowlist)
+  - or `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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.
+  - Exhaustive sweeps use `OPENCLAW_LIVE_TEST_TIMEOUT_MS` for the whole direct-model test timeout. Default: 60 minutes.
+  - Direct-model probes run with 20-way parallelism by default; set `OPENCLAW_LIVE_MODEL_CONCURRENCY` to override.
 - How to select providers:
   - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist)
 - Where keys come from:
@@ -79,7 +82,7 @@ Live tests are split into two layers so we can isolate failures:
 - How to enable:
   - `pnpm test:live` (or `OPENCLAW_LIVE_TEST=1` if invoking Vitest directly)
 - How to select models:
-  - Default: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
+  - Default: modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
   - `OPENCLAW_LIVE_GATEWAY_MODELS=all` is an alias for the modern allowlist
   - Or set `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (or comma list) to narrow
   - Modern/all gateway sweeps default to a curated high-signal cap; set `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` for an exhaustive modern sweep or a positive number for a smaller cap.
@@ -114,7 +117,7 @@ openclaw models list --json
   - Default provider/model: `claude-cli/claude-sonnet-4-6`
   - Command/args/image behavior come from the owning CLI backend plugin metadata.
 - Overrides (optional):
-  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
+  - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"`
   - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
   - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
   - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` to send a real image attachment (paths are injected into the prompt).
@@ -127,7 +130,7 @@ Example:
 
 ```bash
 OPENCLAW_LIVE_CLI_BACKEND=1 \
-  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5" \
+  OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2" \
   pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
 ```
 
@@ -177,8 +180,8 @@ Notes:
   - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini`
   - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
   - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
-  - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5`
-  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4`
+  - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2`
+  - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2`
 - Notes:
   - This lane uses the gateway `chat.send` surface with admin-only synthetic originating-route fields so tests can attach message-channel context without pretending to deliver externally.
   - When `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` is unset, the test uses the embedded `acpx` plugin's built-in agent registry for the selected ACP harness agent.
@@ -219,7 +222,7 @@ Docker notes:
   `agent` method:
   - load the bundled `codex` plugin
   - select `OPENCLAW_AGENT_RUNTIME=codex`
-  - send a first gateway agent turn to `openai/gpt-5.4` with the Codex harness forced
+  - send a first gateway agent turn to `openai/gpt-5.2` with the Codex harness forced
   - send a second turn to the same OpenClaw session and verify the app-server
     thread can resume
   - run `/codex status` and `/codex models` through the same gateway command
@@ -229,7 +232,7 @@ Docker notes:
     denied so the agent asks back
 - Test: `src/gateway/gateway-codex-harness.live.test.ts`
 - Enable: `OPENCLAW_LIVE_CODEX_HARNESS=1`
-- Default model: `openai/gpt-5.4`
+- Default model: `openai/gpt-5.2`
 - Optional image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
 - Optional MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
 - Optional Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
@@ -247,7 +250,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \
   OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \
   OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \
   OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \
-  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.4 \
+  OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.2 \
   pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts
 ```
 
@@ -278,13 +281,13 @@ Docker notes:
 Narrow, explicit allowlists are fastest and least flaky:
 
 - Single model, direct (no gateway):
-  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts`
 
 - Single model, gateway smoke:
-  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
 
 - Tool calling across several providers:
-  - `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`
+  - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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`
@@ -307,8 +310,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.4` (optional: `openai/gpt-5.4-mini`)
-- OpenAI Codex OAuth: `openai-codex/gpt-5.5`
+- OpenAI (non-Codex): `openai/gpt-5.2`
+- OpenAI Codex OAuth: `openai-codex/gpt-5.2`
 - 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`
@@ -316,13 +319,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.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`
+`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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.4` (or `openai/gpt-5.4-mini`)
+- OpenAI: `openai/gpt-5.2`
 - 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`

docs/help/testing.md

@@ -50,6 +50,11 @@ When debugging real providers/models (requires real creds):
   - Add new high-signal provider secrets to `scripts/ci-hydrate-live-auth.sh`
     plus `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` and its
     scheduled/release callers.
+- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind`
+  - Runs a Docker live lane against the Codex app-server path, binds a synthetic
+    Slack DM with `/codex bind`, exercises `/codex fast` and
+    `/codex permissions`, then verifies a plain reply and an image attachment
+    route through the native plugin binding instead of ACP.
 - Moonshot/Kimi cost smoke: with `MOONSHOT_API_KEY` set, run
   `openclaw models list --provider moonshot --json`, then run an isolated
   `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`
@@ -101,6 +106,13 @@ runs the same lanes before release approval.
     endpoint.
   - Use `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` to run the same packaged-install
     lane with Discord.
+- `pnpm test:docker:npm-telegram-live`
+  - Installs a published OpenClaw package in Docker, runs installed-package
+    onboarding, configures Telegram through the installed CLI, then reuses the
+    live Telegram QA lane with that installed package as the SUT Gateway.
+  - Defaults to `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`.
+  - Uses the same Telegram env credentials or Convex credential source as
+    `pnpm openclaw qa telegram`.
 - `pnpm test:docker:bundled-channel-deps`
   - Packs and installs the current OpenClaw build in Docker, starts the Gateway
     with OpenAI configured, then enables bundled channel/plugins via config
@@ -694,3 +706,8 @@ When you fix a provider/model issue discovered in live:
 - SecretRef traversal guardrail:
   - `src/secrets/exec-secret-ref-id-parity.test.ts` derives one sampled target per SecretRef class from registry metadata (`listSecretTargetRegistryEntries()`), then asserts traversal-segment exec ids are rejected.
   - If you add a new `includeInPlan` SecretRef target family in `src/secrets/target-registry-data.ts`, update `classifyTargetClass` in that test. The test intentionally fails on unclassified target ids so new classes cannot be skipped silently.
+
+## Related
+
+- [Testing live](/help/testing-live)
+- [CI](/ci)

docs/network.md

@@ -67,3 +67,8 @@ Local trust:
 - [Gateway config reference](/gateway/configuration)
 - [Troubleshooting](/gateway/troubleshooting)
 - [Doctor](/gateway/doctor)
+
+## Related
+
+- [Gateway network model](/gateway/network-model)
+- [Remote access](/gateway/remote)

docs/perplexity.md

@@ -179,3 +179,8 @@ await web_search({
 
 See [Web tools](/tools/web) for the full web_search configuration.
 See [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) for more details.
+
+## Related
+
+- [Perplexity search](/tools/perplexity-search)
+- [Web search](/tools/web)

docs/pi-dev.md

@@ -76,3 +76,7 @@ If you only want to reset sessions, delete `agents/<agentId>/sessions/` for that
 
 - [Testing](/help/testing)
 - [Getting Started](/start/getting-started)
+
+## Related
+
+- [Pi integration architecture](/pi)

docs/pi.md

@@ -566,3 +566,8 @@ Live/opt-in:
 - `src/agents/pi-embedded-runner-extraparams.live.test.ts` (enable `OPENCLAW_LIVE_TEST=1`)
 
 For current run commands, see [Pi Development Workflow](/pi-dev).
+
+## Related
+
+- [Pi development workflow](/pi-dev)
+- [Install overview](/install)

docs/plan/codex-context-engine-harness.md

@@ -0,0 +1,626 @@
+---
+title: "Codex Harness Context Engine Port"
+summary: "Specification for making the bundled Codex app-server harness honor OpenClaw context-engine plugins"
+read_when:
+  - You are wiring context-engine lifecycle behavior into the Codex harness
+  - You need lossless-claw or another context-engine plugin to work with codex/* embedded harness sessions
+  - You are comparing embedded PI and Codex app-server context behavior
+---
+
+# Codex Harness Context Engine Port
+
+## Status
+
+Draft implementation specification.
+
+## Goal
+
+Make the bundled Codex app-server harness honor the same OpenClaw context-engine
+lifecycle contract that embedded PI turns already honor.
+
+A session using `agents.defaults.embeddedHarness.runtime: "codex"` or a
+`codex/*` model should still let the selected context-engine plugin, such as
+`lossless-claw`, control context assembly, post-turn ingest, maintenance, and
+OpenClaw-level compaction policy as far as the Codex app-server boundary allows.
+
+## Non-goals
+
+- Do not reimplement Codex app-server internals.
+- Do not make Codex native thread compaction produce a lossless-claw summary.
+- Do not require non-Codex models to use the Codex harness.
+- Do not change ACP/acpx session behavior. This specification is for the
+  non-ACP embedded agent harness path only.
+- Do not make third-party plugins register Codex app-server extension factories;
+  the existing bundled-plugin trust boundary remains unchanged.
+
+## Current architecture
+
+The embedded run loop resolves the configured context engine once per run before
+selecting a concrete low-level harness:
+
+- `src/agents/pi-embedded-runner/run.ts`
+  - initializes context-engine plugins
+  - calls `resolveContextEngine(params.config)`
+  - passes `contextEngine` and `contextTokenBudget` into
+    `runEmbeddedAttemptWithBackend(...)`
+
+`runEmbeddedAttemptWithBackend(...)` delegates to the selected agent harness:
+
+- `src/agents/pi-embedded-runner/run/backend.ts`
+- `src/agents/harness/selection.ts`
+
+The Codex app-server harness is registered by the bundled Codex plugin:
+
+- `extensions/codex/index.ts`
+- `extensions/codex/harness.ts`
+
+The Codex harness implementation receives the same `EmbeddedRunAttemptParams`
+as PI-backed attempts:
+
+- `extensions/codex/src/app-server/run-attempt.ts`
+
+That means the required hook point is in OpenClaw-controlled code. The external
+boundary is the Codex app-server protocol itself: OpenClaw can control what it
+sends to `thread/start`, `thread/resume`, and `turn/start`, and can observe
+notifications, but it cannot change Codex's internal thread store or native
+compactor.
+
+## Current gap
+
+Embedded PI attempts call the context-engine lifecycle directly:
+
+- bootstrap/maintenance before the attempt
+- assemble before the model call
+- afterTurn or ingest after the attempt
+- maintenance after a successful turn
+- context-engine compaction for engines that own compaction
+
+Relevant PI code:
+
+- `src/agents/pi-embedded-runner/run/attempt.ts`
+- `src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts`
+- `src/agents/pi-embedded-runner/context-engine-maintenance.ts`
+
+Codex app-server attempts currently run generic agent-harness hooks and mirror
+the transcript, but do not call `params.contextEngine.bootstrap`,
+`params.contextEngine.assemble`, `params.contextEngine.afterTurn`,
+`params.contextEngine.ingestBatch`, `params.contextEngine.ingest`, or
+`params.contextEngine.maintain`.
+
+Relevant Codex code:
+
+- `extensions/codex/src/app-server/run-attempt.ts`
+- `extensions/codex/src/app-server/thread-lifecycle.ts`
+- `extensions/codex/src/app-server/event-projector.ts`
+- `extensions/codex/src/app-server/compact.ts`
+
+## Desired behavior
+
+For Codex harness turns, OpenClaw should preserve this lifecycle:
+
+1. Read the mirrored OpenClaw session transcript.
+2. Bootstrap the active context engine when a previous session file exists.
+3. Run bootstrap maintenance when available.
+4. Assemble context using the active context engine.
+5. Convert the assembled context into Codex-compatible inputs.
+6. Start or resume the Codex thread with developer instructions that include any
+   context-engine `systemPromptAddition`.
+7. Start the Codex turn with the assembled user-facing prompt.
+8. Mirror the Codex result back into the OpenClaw transcript.
+9. Call `afterTurn` if implemented, otherwise `ingestBatch`/`ingest`, using the
+   mirrored transcript snapshot.
+10. Run turn maintenance after successful non-aborted turns.
+11. Preserve Codex native compaction signals and OpenClaw compaction hooks.
+
+## Design constraints
+
+### Codex app-server remains canonical for native thread state
+
+Codex owns its native thread and any internal extended history. OpenClaw should
+not try to mutate the app-server's internal history except through supported
+protocol calls.
+
+OpenClaw's transcript mirror remains the source for OpenClaw features:
+
+- chat history
+- search
+- `/new` and `/reset` bookkeeping
+- future model or harness switching
+- context-engine plugin state
+
+### Context engine assembly must be projected into Codex inputs
+
+The context-engine interface returns OpenClaw `AgentMessage[]`, not a Codex
+thread patch. Codex app-server `turn/start` accepts a current user input, while
+`thread/start` and `thread/resume` accept developer instructions.
+
+Therefore the implementation needs a projection layer. The safe first version
+should avoid pretending it can replace Codex internal history. It should inject
+assembled context as deterministic prompt/developer-instruction material around
+the current turn.
+
+### Prompt-cache stability matters
+
+For engines like lossless-claw, the assembled context should be deterministic
+for unchanged inputs. Do not add timestamps, random ids, or nondeterministic
+ordering to generated context text.
+
+### PI fallback semantics do not change
+
+Harness selection remains as-is:
+
+- `runtime: "pi"` forces PI
+- `runtime: "codex"` selects the registered Codex harness
+- `runtime: "auto"` lets plugin harnesses claim supported providers
+- `fallback: "none"` disables PI fallback when no plugin harness matches
+
+This work changes what happens after the Codex harness is selected.
+
+## Implementation plan
+
+### 1. Export or relocate reusable context-engine attempt helpers
+
+Today the reusable lifecycle helpers live under the PI runner:
+
+- `src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts`
+- `src/agents/pi-embedded-runner/run/attempt.prompt-helpers.ts`
+- `src/agents/pi-embedded-runner/context-engine-maintenance.ts`
+
+Codex should not import from an implementation path whose name implies PI if we
+can avoid it.
+
+Create a harness-neutral module, for example:
+
+- `src/agents/harness/context-engine-lifecycle.ts`
+
+Move or re-export:
+
+- `runAttemptContextEngineBootstrap`
+- `assembleAttemptContextEngine`
+- `finalizeAttemptContextEngineTurn`
+- `buildAfterTurnRuntimeContext`
+- `buildAfterTurnRuntimeContextFromUsage`
+- a small wrapper around `runContextEngineMaintenance`
+
+Keep PI imports working either by re-exporting from the old files or updating PI
+call sites in the same PR.
+
+The neutral helper names should not mention PI.
+
+Suggested names:
+
+- `bootstrapHarnessContextEngine`
+- `assembleHarnessContextEngine`
+- `finalizeHarnessContextEngineTurn`
+- `buildHarnessContextEngineRuntimeContext`
+- `runHarnessContextEngineMaintenance`
+
+### 2. Add a Codex context projection helper
+
+Add a new module:
+
+- `extensions/codex/src/app-server/context-engine-projection.ts`
+
+Responsibilities:
+
+- Accept the assembled `AgentMessage[]`, original mirrored history, and current
+  prompt.
+- Determine which context belongs in developer instructions vs current user
+  input.
+- Preserve the current user prompt as the final actionable request.
+- Render prior messages in a stable, explicit format.
+- Avoid volatile metadata.
+
+Proposed API:
+
+```ts
+export type CodexContextProjection = {
+  developerInstructionAddition?: string;
+  promptText: string;
+  assembledMessages: AgentMessage[];
+  prePromptMessageCount: number;
+};
+
+export function projectContextEngineAssemblyForCodex(params: {
+  assembledMessages: AgentMessage[];
+  originalHistoryMessages: AgentMessage[];
+  prompt: string;
+  systemPromptAddition?: string;
+}): CodexContextProjection;
+```
+
+Recommended first projection:
+
+- Put `systemPromptAddition` into developer instructions.
+- Put the assembled transcript context before the current prompt in `promptText`.
+- Label it clearly as OpenClaw assembled context.
+- Keep current prompt last.
+- Exclude duplicate current user prompt if it already appears at the tail.
+
+Example prompt shape:
+
+```text
+OpenClaw assembled context for this turn:
+
+<conversation_context>
+[user]
+...
+
+[assistant]
+...
+</conversation_context>
+
+Current user request:
+...
+```
+
+This is less elegant than native Codex history surgery, but it is implementable
+inside OpenClaw and preserves context-engine semantics.
+
+Future improvement: if Codex app-server exposes a protocol for replacing or
+supplementing thread history, swap this projection layer to use that API.
+
+### 3. Wire bootstrap before Codex thread startup
+
+In `extensions/codex/src/app-server/run-attempt.ts`:
+
+- Read mirrored session history as today.
+- Determine whether the session file existed before this run. Prefer a helper
+  that checks `fs.stat(params.sessionFile)` before mirroring writes.
+- Open a `SessionManager` or use a narrow session manager adapter if the helper
+  requires it.
+- Call the neutral bootstrap helper when `params.contextEngine` exists.
+
+Pseudo-flow:
+
+```ts
+const hadSessionFile = await fileExists(params.sessionFile);
+const sessionManager = SessionManager.open(params.sessionFile);
+const historyMessages = sessionManager.buildSessionContext().messages;
+
+await bootstrapHarnessContextEngine({
+  hadSessionFile,
+  contextEngine: params.contextEngine,
+  sessionId: params.sessionId,
+  sessionKey: sandboxSessionKey,
+  sessionFile: params.sessionFile,
+  sessionManager,
+  runtimeContext: buildHarnessContextEngineRuntimeContext(...),
+  runMaintenance: runHarnessContextEngineMaintenance,
+  warn,
+});
+```
+
+Use the same `sessionKey` convention as the Codex tool bridge and transcript
+mirror. Today Codex computes `sandboxSessionKey` from `params.sessionKey` or
+`params.sessionId`; use that consistently unless there is a reason to preserve
+raw `params.sessionKey`.
+
+### 4. Wire assemble before `thread/start` / `thread/resume` and `turn/start`
+
+In `runCodexAppServerAttempt`:
+
+1. Build dynamic tools first, so the context engine sees the actual available
+   tool names.
+2. Read mirrored session history.
+3. Run context-engine `assemble(...)` when `params.contextEngine` exists.
+4. Project the assembled result into:
+   - developer instruction addition
+   - prompt text for `turn/start`
+
+The existing hook call:
+
+```ts
+resolveAgentHarnessBeforePromptBuildResult({
+  prompt: params.prompt,
+  developerInstructions: buildDeveloperInstructions(params),
+  messages: historyMessages,
+  ctx: hookContext,
+});
+```
+
+should become context-aware:
+
+1. compute base developer instructions with `buildDeveloperInstructions(params)`
+2. apply context-engine assembly/projection
+3. run `before_prompt_build` with the projected prompt/developer instructions
+
+This order lets generic prompt hooks see the same prompt Codex will receive. If
+we need strict PI parity, run context-engine assembly before hook composition,
+because PI applies context-engine `systemPromptAddition` to the final system
+prompt after its prompt pipeline. The important invariant is that both context
+engine and hooks get a deterministic, documented order.
+
+Recommended order for first implementation:
+
+1. `buildDeveloperInstructions(params)`
+2. context-engine `assemble()`
+3. append/prepend `systemPromptAddition` to developer instructions
+4. project assembled messages into prompt text
+5. `resolveAgentHarnessBeforePromptBuildResult(...)`
+6. pass final developer instructions to `startOrResumeThread(...)`
+7. pass final prompt text to `buildTurnStartParams(...)`
+
+The spec should be encoded in tests so future changes do not reorder it by
+accident.
+
+### 5. Preserve prompt-cache stable formatting
+
+The projection helper must produce byte-stable output for identical inputs:
+
+- stable message order
+- stable role labels
+- no generated timestamps
+- no object key order leakage
+- no random delimiters
+- no per-run ids
+
+Use fixed delimiters and explicit sections.
+
+### 6. Wire post-turn after transcript mirroring
+
+Codex's `CodexAppServerEventProjector` builds a local `messagesSnapshot` for the
+current turn. `mirrorTranscriptBestEffort(...)` writes that snapshot into the
+OpenClaw transcript mirror.
+
+After mirroring succeeds or fails, call the context-engine finalizer with the
+best available message snapshot:
+
+- Prefer full mirrored session context after the write, because `afterTurn`
+  expects the session snapshot, not only the current turn.
+- Fall back to `historyMessages + result.messagesSnapshot` if the session file
+  cannot be reopened.
+
+Pseudo-flow:
+
+```ts
+const prePromptMessageCount = historyMessages.length;
+await mirrorTranscriptBestEffort(...);
+const finalMessages = readMirroredSessionHistoryMessages(params.sessionFile)
+  ?? [...historyMessages, ...result.messagesSnapshot];
+
+await finalizeHarnessContextEngineTurn({
+  contextEngine: params.contextEngine,
+  promptError: Boolean(finalPromptError),
+  aborted: finalAborted,
+  yieldAborted,
+  sessionIdUsed: params.sessionId,
+  sessionKey: sandboxSessionKey,
+  sessionFile: params.sessionFile,
+  messagesSnapshot: finalMessages,
+  prePromptMessageCount,
+  tokenBudget: params.contextTokenBudget,
+  runtimeContext: buildHarnessContextEngineRuntimeContextFromUsage({
+    attempt: params,
+    workspaceDir: effectiveWorkspace,
+    agentDir,
+    tokenBudget: params.contextTokenBudget,
+    lastCallUsage: result.attemptUsage,
+    promptCache: result.promptCache,
+  }),
+  runMaintenance: runHarnessContextEngineMaintenance,
+  sessionManager,
+  warn,
+});
+```
+
+If mirroring fails, still call `afterTurn` with the fallback snapshot, but log
+that the context engine is ingesting from fallback turn data.
+
+### 7. Normalize usage and prompt-cache runtime context
+
+Codex results include normalized usage from app-server token notifications when
+available. Pass that usage into the context-engine runtime context.
+
+If Codex app-server eventually exposes cache read/write details, map them into
+`ContextEnginePromptCacheInfo`. Until then, omit `promptCache` rather than
+inventing zeros.
+
+### 8. Compaction policy
+
+There are two compaction systems:
+
+1. OpenClaw context-engine `compact()`
+2. Codex app-server native `thread/compact/start`
+
+Do not silently conflate them.
+
+#### `/compact` and explicit OpenClaw compaction
+
+When the selected context engine has `info.ownsCompaction === true`, explicit
+OpenClaw compaction should prefer the context engine's `compact()` result for
+the OpenClaw transcript mirror and plugin state.
+
+When the selected Codex harness has a native thread binding, we may additionally
+request Codex native compaction to keep the app-server thread healthy, but this
+must be reported as a separate backend action in details.
+
+Recommended behavior:
+
+- If `contextEngine.info.ownsCompaction === true`:
+  - call context-engine `compact()` first
+  - then best-effort call Codex native compaction when a thread binding exists
+  - return the context-engine result as the primary result
+  - include Codex native compaction status in `details.codexNativeCompaction`
+- If the active context engine does not own compaction:
+  - preserve current Codex native compaction behavior
+
+This likely requires changing `extensions/codex/src/app-server/compact.ts` or
+wrapping it from the generic compaction path, depending on where
+`maybeCompactAgentHarnessSession(...)` is invoked.
+
+#### In-turn Codex native contextCompaction events
+
+Codex may emit `contextCompaction` item events during a turn. Keep the current
+before/after compaction hook emission in `event-projector.ts`, but do not treat
+that as a completed context-engine compaction.
+
+For engines that own compaction, emit an explicit diagnostic when Codex performs
+native compaction anyway:
+
+- stream/event name: existing `compaction` stream is acceptable
+- details: `{ backend: "codex-app-server", ownsCompaction: true }`
+
+This makes the split auditable.
+
+### 9. Session reset and binding behavior
+
+The existing Codex harness `reset(...)` clears the Codex app-server binding from
+the OpenClaw session file. Preserve that behavior.
+
+Also ensure context-engine state cleanup continues to happen through existing
+OpenClaw session lifecycle paths. Do not add Codex-specific cleanup unless the
+context-engine lifecycle currently misses reset/delete events for all harnesses.
+
+### 10. Error handling
+
+Follow PI semantics:
+
+- bootstrap failures warn and continue
+- assemble failures warn and fall back to unassembled pipeline messages/prompt
+- afterTurn/ingest failures warn and mark post-turn finalization unsuccessful
+- maintenance runs only after successful, non-aborted, non-yield turns
+- compaction errors should not be retried as fresh prompts
+
+Codex-specific additions:
+
+- If context projection fails, warn and fall back to the original prompt.
+- If transcript mirror fails, still attempt context-engine finalization with
+  fallback messages.
+- If Codex native compaction fails after context-engine compaction succeeds,
+  do not fail the whole OpenClaw compaction when the context engine is primary.
+
+## Test plan
+
+### Unit tests
+
+Add tests under `extensions/codex/src/app-server`:
+
+1. `run-attempt.context-engine.test.ts`
+   - Codex calls `bootstrap` when a session file exists.
+   - Codex calls `assemble` with mirrored messages, token budget, tool names,
+     citations mode, model id, and prompt.
+   - `systemPromptAddition` is included in developer instructions.
+   - Assembled messages are projected into the prompt before current request.
+   - Codex calls `afterTurn` after transcript mirroring.
+   - Without `afterTurn`, Codex calls `ingestBatch` or per-message `ingest`.
+   - Turn maintenance runs after successful turns.
+   - Turn maintenance does not run on prompt error, abort, or yield abort.
+
+2. `context-engine-projection.test.ts`
+   - stable output for identical inputs
+   - no duplicate current prompt when assembled history includes it
+   - handles empty history
+   - preserves role order
+   - includes system prompt addition only in developer instructions
+
+3. `compact.context-engine.test.ts`
+   - owning context engine primary result wins
+   - Codex native compaction status appears in details when also attempted
+   - Codex native failure does not fail owning context-engine compaction
+   - non-owning context engine preserves current native compaction behavior
+
+### Existing tests to update
+
+- `extensions/codex/src/app-server/run-attempt.test.ts` if present, otherwise
+  nearest Codex app-server run tests.
+- `extensions/codex/src/app-server/event-projector.test.ts` only if compaction
+  event details change.
+- `src/agents/harness/selection.test.ts` should not need changes unless config
+  behavior changes; it should remain stable.
+- PI context-engine tests should continue to pass unchanged.
+
+### Integration / live tests
+
+Add or extend live Codex harness smoke tests:
+
+- configure `plugins.slots.contextEngine` to a test engine
+- configure `agents.defaults.model` to a `codex/*` model
+- configure `agents.defaults.embeddedHarness.runtime = "codex"`
+- assert test engine observed:
+  - bootstrap
+  - assemble
+  - afterTurn or ingest
+  - maintenance
+
+Avoid requiring lossless-claw in OpenClaw core tests. Use a small in-repo fake
+context engine plugin.
+
+## Observability
+
+Add debug logs around Codex context-engine lifecycle calls:
+
+- `codex context engine bootstrap started/completed/failed`
+- `codex context engine assemble applied`
+- `codex context engine finalize completed/failed`
+- `codex context engine maintenance skipped` with reason
+- `codex native compaction completed alongside context-engine compaction`
+
+Avoid logging full prompts or transcript contents.
+
+Add structured fields where useful:
+
+- `sessionId`
+- `sessionKey` redacted or omitted according to existing logging practice
+- `engineId`
+- `threadId`
+- `turnId`
+- `assembledMessageCount`
+- `estimatedTokens`
+- `hasSystemPromptAddition`
+
+## Migration / compatibility
+
+This should be backward-compatible:
+
+- If no context engine is configured, legacy context engine behavior should be
+  equivalent to today's Codex harness behavior.
+- If context-engine `assemble` fails, Codex should continue with the original
+  prompt path.
+- Existing Codex thread bindings should remain valid.
+- Dynamic tool fingerprinting should not include context-engine output; otherwise
+  every context change could force a new Codex thread. Only the tool catalog
+  should affect the dynamic tool fingerprint.
+
+## Open questions
+
+1. Should assembled context be injected entirely into the user prompt, entirely
+   into developer instructions, or split?
+
+   Recommendation: split. Put `systemPromptAddition` in developer instructions;
+   put assembled transcript context in the user prompt wrapper. This best matches
+   the current Codex protocol without mutating native thread history.
+
+2. Should Codex native compaction be disabled when a context engine owns
+   compaction?
+
+   Recommendation: no, not initially. Codex native compaction may still be
+   necessary to keep the app-server thread alive. But it must be reported as
+   native Codex compaction, not as context-engine compaction.
+
+3. Should `before_prompt_build` run before or after context-engine assembly?
+
+   Recommendation: after context-engine projection for Codex, so generic harness
+   hooks see the actual prompt/developer instructions Codex will receive. If PI
+   parity requires the opposite, encode the chosen order in tests and document it
+   here.
+
+4. Can Codex app-server accept a future structured context/history override?
+
+   Unknown. If it can, replace the text projection layer with that protocol and
+   keep the lifecycle calls unchanged.
+
+## Acceptance criteria
+
+- A `codex/*` embedded harness turn invokes the selected context engine's
+  assemble lifecycle.
+- A context-engine `systemPromptAddition` affects Codex developer instructions.
+- Assembled context affects the Codex turn input deterministically.
+- Successful Codex turns call `afterTurn` or ingest fallback.
+- Successful Codex turns run context-engine turn maintenance.
+- Failed/aborted/yield-aborted turns do not run turn maintenance.
+- Context-engine-owned compaction remains primary for OpenClaw/plugin state.
+- Codex native compaction remains auditable as native Codex behavior.
+- Existing PI context-engine behavior is unchanged.
+- Existing Codex harness behavior is unchanged when no non-legacy context engine
+  is selected or when assembly fails.

docs/plan/ui-channels.md

@@ -250,3 +250,8 @@ Add or update:
 - Should `delivery.pin` be implemented for Discord, Slack, MS Teams, and Feishu in the first pass, or only Telegram first?
 - Should `delivery` eventually absorb existing fields such as `replyToId`, `replyToCurrent`, `silent`, and `audioAsVoice`, or stay focused on post-send behaviors?
 - Should presentation support images or file references directly, or should media remain separate from UI layout for now?
+
+## Related
+
+- [Channels overview](/channels)
+- [Message presentation](/plugins/message-presentation)

docs/platforms/digitalocean.md

@@ -258,7 +258,7 @@ free -h
 
 ---
 
-## See Also
+## Related
 
 - [Hetzner guide](/install/hetzner) — cheaper, more powerful
 - [Docker install](/install/docker) — containerized setup

docs/platforms/mac/bundled-gateway.md

@@ -71,3 +71,8 @@ Then:
 ```bash
 openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000
 ```
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway runbook](/gateway)

docs/platforms/mac/canvas.md

@@ -121,3 +121,8 @@ The app prompts for confirmation unless a valid key is provided.
 - Canvas scheme blocks directory traversal; files must live under the session root.
 - Local Canvas content uses a custom scheme (no loopback server required).
 - External `http(s)` URLs are allowed only when explicitly navigated.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [WebChat](/web/webchat)

docs/platforms/mac/child-process.md

@@ -67,3 +67,8 @@ remote host and connects over that tunnel.
 
 If a true child‑process mode is ever needed again, it should be documented as a
 separate, explicit dev‑only mode.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway runbook](/gateway)

docs/platforms/mac/dev-setup.md

@@ -105,3 +105,8 @@ lsof -nP -iTCP:18789 -sTCP:LISTEN
 ```
 
 If a manual run is holding the port, stop that process (Ctrl+C). As a last resort, kill the PID you found above.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Install overview](/install)

docs/platforms/mac/health.md

@@ -32,3 +32,8 @@ How to see whether the linked channel is healthy from the menu bar app.
 ## When in doubt
 
 - You can still use the CLI flow in [Gateway health](/gateway/health) (`openclaw status`, `openclaw status --deep`, `openclaw health --json`) and tail `/tmp/openclaw/openclaw-*.log` for `web-heartbeat` / `web-reconnect`.
+
+## Related
+
+- [Gateway health](/gateway/health)
+- [macOS app](/platforms/macos)

docs/platforms/mac/icon.md

@@ -29,3 +29,8 @@ Behavioral notes
 
 - No external CLI/broker toggle for ears/working; keep it internal to the app’s own signals to avoid accidental flapping.
 - Keep TTLs short (<10s) so the icon returns to baseline quickly if a job hangs.
+
+## Related
+
+- [Menu bar](/platforms/mac/menu-bar)
+- [macOS app](/platforms/macos)

docs/platforms/mac/logging.md

@@ -55,3 +55,8 @@ sudo install -m 644 -o root -g wheel /tmp/ai.openclaw.plist /Library/Preferences
 - Remove the override: `sudo rm /Library/Preferences/Logging/Subsystems/ai.openclaw.plist`.
 - Optionally run `sudo log config --reload` to force logd to drop the override immediately.
 - Remember this surface can include phone numbers and message bodies; keep the plist in place only while you actively need the extra detail.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Gateway logging](/gateway/logging)

docs/platforms/mac/menu-bar.md

@@ -79,3 +79,8 @@ title: "Menu bar"
 - Start main while other active: icon flips to main instantly.
 - Rapid tool bursts: ensure badge does not flicker (TTL grace on tool results).
 - Health row reappears once all sessions idle.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Menu bar icon](/platforms/mac/icon)

docs/platforms/mac/peekaboo.md

@@ -61,3 +61,8 @@ If you need longer retention, re‑capture from the client.
   in **debug** mode only.
 - If no hosts are found, open one of the host apps (Peekaboo.app or OpenClaw.app)
   and confirm permissions are granted.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS permissions](/platforms/mac/permissions)

docs/platforms/mac/permissions.md

@@ -46,3 +46,8 @@ Workaround: move files into the OpenClaw workspace (`~/.openclaw/workspace`) if
 
 If you are testing permissions, always sign with a real certificate. Ad-hoc
 builds are only acceptable for quick local runs where permissions do not matter.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS signing](/platforms/mac/signing)

docs/platforms/mac/remote.md

@@ -2,7 +2,7 @@
 summary: "macOS app flow for controlling a remote OpenClaw gateway over SSH"
 read_when:
   - Setting up or debugging remote mac control
-title: "Remote Control"
+title: "Remote control"
 ---
 
 # Remote OpenClaw (macOS ⇄ remote host)
@@ -82,3 +82,8 @@ openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" -
 ```
 
 There is no global “default sound” toggle in the app anymore; callers choose a sound (or none) per request.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [Remote access](/gateway/remote)

docs/platforms/mac/signing.md

@@ -45,3 +45,8 @@ The About tab reads these keys to show version, build date, git commit, and whet
 ## Why
 
 TCC permissions are tied to the bundle identifier _and_ code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Signing the binaries (ad‑hoc by default) and keeping a fixed bundle id/path (`dist/OpenClaw.app`) preserves the grants between builds, matching the VibeTunnel approach.
+
+## Related
+
+- [macOS app](/platforms/macos)
+- [macOS permissions](/platforms/mac/permissions)

docs/platforms/mac/skills.md

@@ -36,3 +36,8 @@ The macOS app surfaces OpenClaw skills via the gateway; it does not parse skills
 ## Remote mode
 
 - Install + config updates happen on the gateway host (not the local Mac).
+
+## Related
+
+- [Skills](/tools/skills)
+- [macOS app](/platforms/macos)