重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。

同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
2026-10-09 21:30:45 +08:00 · 2026-04-26 08:34:33 +08:00 · 2026-04-26 08:34:33 +08:00 · dbbe3add6a
commit dbbe3add6a
parent 4a23b715a2
14438 changed files with 2693620 additions and 2546 deletions
--- a/openclaw/docs/.generated/README.md
+++ b/openclaw/docs/.generated/README.md
@ -0,0 +1,21 @@
+# Generated Docs Artifacts
+
+SHA-256 hash files are the tracked drift-detection artifacts. The full JSON
+baselines are generated locally (gitignored) for inspection only.
+
+**Tracked (committed to git):**
+
+- `config-baseline.sha256` — hashes of config baseline JSON artifacts.
+- `plugin-sdk-api-baseline.sha256` — hashes of Plugin SDK API baseline artifacts.
+
+**Local only (gitignored):**
+
+- `config-baseline.json`, `config-baseline.core.json`, `config-baseline.channel.json`, `config-baseline.plugin.json`
+- `plugin-sdk-api-baseline.json`, `plugin-sdk-api-baseline.jsonl`
+
+Do not edit any of these files by hand.
+
+- Regenerate config baseline: `pnpm config:docs:gen`
+- Validate config baseline: `pnpm config:docs:check`
+- Regenerate Plugin SDK API baseline: `pnpm plugin-sdk:api:gen`
+- Validate Plugin SDK API baseline: `pnpm plugin-sdk:api:check`
--- a/openclaw/docs/.generated/config-baseline.sha256
+++ b/openclaw/docs/.generated/config-baseline.sha256
@ -0,0 +1,4 @@
+b199851e694368264c24ba3d347a84764a19f632769e049fe94a82787c5e5d93  config-baseline.json
+cbb9a6ee1cb69068d5eb63f00f95512ba19778415ea5b2eabe056aaea38978b5  config-baseline.core.json
+0982fc3d264047919333a57dfba1ba948e6639fb19659a400f947dfdd8b8d1de  config-baseline.channel.json
+b695cb31b4c0cf1d31f842f2892e99cc3ff8d84263ae72b72977cae844b81d6e  config-baseline.plugin.json
--- a/openclaw/docs/.generated/plugin-sdk-api-baseline.sha256
+++ b/openclaw/docs/.generated/plugin-sdk-api-baseline.sha256
@ -0,0 +1,2 @@
+cf682f7ed83294f79b72758a9bfa0a720da38f967e249bae5bfa916b2a5f0238  plugin-sdk-api-baseline.json
+67c723fb639384f457b2900bc1f2bf2639462ae0d2091e6984b77fd9c5c30251  plugin-sdk-api-baseline.jsonl
--- a/openclaw/docs/.i18n/README.md
+++ b/openclaw/docs/.i18n/README.md
@ -0,0 +1,72 @@
+# OpenClaw docs i18n assets
+
+This folder stores translation config for the source docs repo.
+
+Generated locale trees and live translation memory now live in the publish repo:
+
+- repo: `openclaw/docs`
+- local checkout: `~/Projects/openclaw-docs`
+
+## Source of truth
+
+- English docs are authored in `openclaw/openclaw`.
+- The source docs tree lives under `docs/`.
+- The source repo no longer keeps committed generated locale trees such as `docs/zh-CN/**`, `docs/ja-JP/**`, `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/uk/**`, `docs/id/**`, or `docs/pl/**`.
+
+## End-to-end flow
+
+1. Edit English docs in `openclaw/openclaw`.
+2. Push to `main`.
+3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mirrors the docs tree into `openclaw/docs`.
+4. The sync script rewrites the publish `docs/docs.json` so the generated locale picker blocks exist there even though they are no longer committed in the source repo.
+5. `openclaw/docs/.github/workflows/translate-zh-cn.yml` refreshes `docs/zh-CN/**` once a day, on demand, and after source-repo release dispatches.
+6. `openclaw/docs/.github/workflows/translate-ja-jp.yml` does the same for `docs/ja-JP/**`.
+7. `openclaw/docs/.github/workflows/translate-es.yml`, `translate-pt-br.yml`, `translate-ko.yml`, `translate-de.yml`, `translate-fr.yml`, `translate-ar.yml`, `translate-it.yml`, `translate-tr.yml`, `translate-uk.yml`, `translate-id.yml`, and `translate-pl.yml` do the same for `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/uk/**`, `docs/id/**`, and `docs/pl/**`.
+
+## Why the split exists
+
+- Keep generated locale output out of the main product repo.
+- Keep Mintlify on a single published docs tree.
+- Preserve the built-in language switcher by letting the publish repo own generated locale trees.
+
+## Files in this folder
+
+- `glossary.<lang>.json` — preferred term mappings used as prompt guidance.
+- `zh-Hans-navigation.json` — curated zh-Hans Mintlify locale navigation reinserted into the publish repo during sync.
+- `ar-navigation.json`, `de-navigation.json`, `es-navigation.json`, `fr-navigation.json`, `id-navigation.json`, `it-navigation.json`, `ja-navigation.json`, `ko-navigation.json`, `pl-navigation.json`, `pt-BR-navigation.json`, `tr-navigation.json` — starter locale metadata kept alongside the source repo, but the publish sync now clones the full English nav tree for these locales so translated pages are visible in Mintlify without hand-maintaining per-locale nav JSON.
+- `<lang>.tm.jsonl` — translation memory keyed by workflow + model + text hash.
+
+In this repo, generated locale TM files such as `docs/.i18n/zh-CN.tm.jsonl`, `docs/.i18n/ja-JP.tm.jsonl`, `docs/.i18n/es.tm.jsonl`, `docs/.i18n/pt-BR.tm.jsonl`, `docs/.i18n/ko.tm.jsonl`, `docs/.i18n/de.tm.jsonl`, `docs/.i18n/fr.tm.jsonl`, `docs/.i18n/ar.tm.jsonl`, `docs/.i18n/it.tm.jsonl`, `docs/.i18n/tr.tm.jsonl`, `docs/.i18n/uk.tm.jsonl`, `docs/.i18n/id.tm.jsonl`, and `docs/.i18n/pl.tm.jsonl` are intentionally no longer committed.
+
+## Glossary format
+
+`glossary.<lang>.json` is an array of entries:
+
+```json
+{
+  "source": "troubleshooting",
+  "target": "故障排除"
+}
+```
+
+Fields:
+
+- `source`: English (or source) phrase to prefer.
+- `target`: preferred translation output.
+
+## Translation mechanics
+
+- `scripts/docs-i18n` still owns translation generation.
+- Doc mode writes `x-i18n.source_hash` into each translated page.
+- Each publish workflow precomputes a pending file list by comparing the current English source hash to the stored locale `x-i18n.source_hash`.
+- If the pending count is `0`, the expensive translation step is skipped entirely.
+- If there are pending files, the workflow translates only those files.
+- The publish workflow retries transient model-format failures, but unchanged files stay skipped because the same hash check runs on each retry.
+- The source repo also dispatches zh-CN, ja-JP, es, pt-BR, ko, de, fr, ar, it, tr, uk, id, and pl refreshes after published GitHub releases so release docs can catch up without waiting for the daily cron.
+
+## Operational notes
+
+- Sync metadata is written to `.openclaw-sync/source.json` in the publish repo.
+- Source repo secret: `OPENCLAW_DOCS_SYNC_TOKEN`
+- Publish repo secret: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY`
+- If locale output looks stale, check the matching `Translate <locale>` workflow in `openclaw/docs` first.
--- a/openclaw/docs/.i18n/ar-navigation.json
+++ b/openclaw/docs/.i18n/ar-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "ar",
+  "tabs": [
+    {
+      "tab": "ابدأ",
+      "groups": [
+        {
+          "group": "نظرة عامة",
+          "pages": ["ar/index"]
+        },
+        {
+          "group": "الخطوات الأولى",
+          "pages": ["ar/start/getting-started", "ar/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/de-navigation.json
+++ b/openclaw/docs/.i18n/de-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "de",
+  "tabs": [
+    {
+      "tab": "Loslegen",
+      "groups": [
+        {
+          "group": "Überblick",
+          "pages": ["de/index"]
+        },
+        {
+          "group": "Erste Schritte",
+          "pages": ["de/start/getting-started", "de/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/es-navigation.json
+++ b/openclaw/docs/.i18n/es-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "es",
+  "tabs": [
+    {
+      "tab": "Comenzar",
+      "groups": [
+        {
+          "group": "Resumen",
+          "pages": ["es/index"]
+        },
+        {
+          "group": "Primeros pasos",
+          "pages": ["es/start/getting-started", "es/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/fr-navigation.json
+++ b/openclaw/docs/.i18n/fr-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "fr",
+  "tabs": [
+    {
+      "tab": "Commencer",
+      "groups": [
+        {
+          "group": "Vue d'ensemble",
+          "pages": ["fr/index"]
+        },
+        {
+          "group": "Premiers pas",
+          "pages": ["fr/start/getting-started", "fr/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/glossary.ar.json
+++ b/openclaw/docs/.i18n/glossary.ar.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.de.json
+++ b/openclaw/docs/.i18n/glossary.de.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.es.json
+++ b/openclaw/docs/.i18n/glossary.es.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.fr.json
+++ b/openclaw/docs/.i18n/glossary.fr.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.id.json
+++ b/openclaw/docs/.i18n/glossary.id.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.it.json
+++ b/openclaw/docs/.i18n/glossary.it.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.ja-JP.json
+++ b/openclaw/docs/.i18n/glossary.ja-JP.json
@ -0,0 +1,98 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Getting Started",
+    "target": "はじめに"
+  },
+  {
+    "source": "Getting started",
+    "target": "はじめに"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "local loopback",
+    "target": "local loopback"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "Onboarding",
+    "target": "オンボーディング"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Quick start",
+    "target": "クイックスタート"
+  },
+  {
+    "source": "Quick Start",
+    "target": "クイックスタート"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  },
+  {
+    "source": "wizard",
+    "target": "ウィザード"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.ko.json
+++ b/openclaw/docs/.i18n/glossary.ko.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.pl.json
+++ b/openclaw/docs/.i18n/glossary.pl.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.pt-BR.json
+++ b/openclaw/docs/.i18n/glossary.pt-BR.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.tr.json
+++ b/openclaw/docs/.i18n/glossary.tr.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.uk.json
+++ b/openclaw/docs/.i18n/glossary.uk.json
@ -0,0 +1,78 @@
+[
+  {
+    "source": "ACP",
+    "target": "ACP"
+  },
+  {
+    "source": "Active Memory",
+    "target": "Active Memory"
+  },
+  {
+    "source": "ClawHub",
+    "target": "ClawHub"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "Compaction",
+    "target": "Compaction"
+  },
+  {
+    "source": "Cron",
+    "target": "Cron"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway"
+  },
+  {
+    "source": "Heartbeat",
+    "target": "Heartbeat"
+  },
+  {
+    "source": "Mintlify",
+    "target": "Mintlify"
+  },
+  {
+    "source": "Node",
+    "target": "Node"
+  },
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Plugin",
+    "target": "Plugin"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "TaskFlow",
+    "target": "TaskFlow"
+  },
+  {
+    "source": "TUI",
+    "target": "TUI"
+  },
+  {
+    "source": "Webhook",
+    "target": "Webhook"
+  }
+]
--- a/openclaw/docs/.i18n/glossary.zh-CN.json
+++ b/openclaw/docs/.i18n/glossary.zh-CN.json
@ -0,0 +1,390 @@
+[
+  {
+    "source": "OpenClaw",
+    "target": "OpenClaw"
+  },
+  {
+    "source": "Gateway",
+    "target": "Gateway 网关"
+  },
+  {
+    "source": "Pi",
+    "target": "Pi"
+  },
+  {
+    "source": "Skills",
+    "target": "Skills"
+  },
+  {
+    "source": "Skills config",
+    "target": "Skills 配置"
+  },
+  {
+    "source": "Skills Config",
+    "target": "Skills 配置"
+  },
+  {
+    "source": "local loopback",
+    "target": "local loopback"
+  },
+  {
+    "source": "Tailscale",
+    "target": "Tailscale"
+  },
+  {
+    "source": "Getting Started",
+    "target": "入门指南"
+  },
+  {
+    "source": "Getting started",
+    "target": "入门指南"
+  },
+  {
+    "source": "Quick start",
+    "target": "快速开始"
+  },
+  {
+    "source": "Quick Start",
+    "target": "快速开始"
+  },
+  {
+    "source": "Chutes",
+    "target": "Chutes"
+  },
+  {
+    "source": "Qwen",
+    "target": "Qwen"
+  },
+  {
+    "source": "Feishu",
+    "target": "Feishu"
+  },
+  {
+    "source": "WeChat",
+    "target": "微信"
+  },
+  {
+    "source": "Weixin",
+    "target": "微信"
+  },
+  {
+    "source": "Mattermost",
+    "target": "Mattermost"
+  },
+  {
+    "source": "BytePlus (International)",
+    "target": "BytePlus（国际版）"
+  },
+  {
+    "source": "Anthropic (API + Claude CLI)",
+    "target": "Anthropic（API + Claude CLI）"
+  },
+  {
+    "source": "Moonshot AI",
+    "target": "Moonshot AI"
+  },
+  {
+    "source": "Additional bundled variants",
+    "target": "其他内置变体"
+  },
+  {
+    "source": "Diffs",
+    "target": "Diffs"
+  },
+  {
+    "source": "Dreaming",
+    "target": "Dreaming"
+  },
+  {
+    "source": "Capability Cookbook",
+    "target": "能力扩展手册"
+  },
+  {
+    "source": "Setup Wizard Reference",
+    "target": "设置向导参考"
+  },
+  {
+    "source": "CLI Setup Reference",
+    "target": "CLI 设置参考"
+  },
+  {
+    "source": "Setup Wizard (CLI)",
+    "target": "设置向导（CLI）"
+  },
+  {
+    "source": "Docs directory",
+    "target": "文档目录"
+  },
+  {
+    "source": "Credits",
+    "target": "致谢"
+  },
+  {
+    "source": "Features",
+    "target": "功能"
+  },
+  {
+    "source": "DMs",
+    "target": "私信"
+  },
+  {
+    "source": "DM",
+    "target": "私信"
+  },
+  {
+    "source": "sandbox",
+    "target": "沙箱"
+  },
+  {
+    "source": "Sandbox",
+    "target": "沙箱"
+  },
+  {
+    "source": "sandboxing",
+    "target": "沙箱隔离"
+  },
+  {
+    "source": "Sandboxing",
+    "target": "沙箱隔离"
+  },
+  {
+    "source": "sandboxed",
+    "target": "沙箱隔离"
+  },
+  {
+    "source": "Sandboxed",
+    "target": "沙箱隔离"
+  },
+  {
+    "source": "Sandboxing note",
+    "target": "沙箱注意事项"
+  },
+  {
+    "source": "Companion apps",
+    "target": "配套应用"
+  },
+  {
+    "source": "expected keys",
+    "target": "预期键名"
+  },
+  {
+    "source": "block streaming",
+    "target": "分块流式传输"
+  },
+  {
+    "source": "Block streaming",
+    "target": "分块流式传输"
+  },
+  {
+    "source": "Discovery + transports",
+    "target": "设备发现 + 传输协议"
+  },
+  {
+    "source": "Discovery",
+    "target": "设备发现"
+  },
+  {
+    "source": "Network model",
+    "target": "网络模型"
+  },
+  {
+    "source": "Bridge protocol (legacy nodes, historical)",
+    "target": "Bridge protocol（旧版节点，历史参考）"
+  },
+  {
+    "source": "Doctor",
+    "target": "Doctor"
+  },
+  {
+    "source": "Memory Wiki",
+    "target": "Memory Wiki"
+  },
+  {
+    "source": "wiki",
+    "target": "wiki"
+  },
+  {
+    "source": "Polls",
+    "target": "投票"
+  },
+  {
+    "source": "QQ Bot",
+    "target": "QQ Bot"
+  },
+  {
+    "source": "Release Policy",
+    "target": "发布策略"
+  },
+  {
+    "source": "Release policy",
+    "target": "发布策略"
+  },
+  {
+    "source": "for full details",
+    "target": "了解详情"
+  },
+  {
+    "source": "First 60 seconds",
+    "target": "最初的六十秒"
+  },
+  {
+    "source": "Auth: where it lives (important)",
+    "target": "凭证：存储位置（重要）"
+  },
+  {
+    "source": "agent",
+    "target": "智能体"
+  },
+  {
+    "source": "channel",
+    "target": "渠道"
+  },
+  {
+    "source": "session",
+    "target": "会话"
+  },
+  {
+    "source": "provider",
+    "target": "提供商"
+  },
+  {
+    "source": "model",
+    "target": "模型"
+  },
+  {
+    "source": "tool",
+    "target": "工具"
+  },
+  {
+    "source": "CLI",
+    "target": "CLI"
+  },
+  {
+    "source": "/cli/gateway",
+    "target": "/cli/gateway"
+  },
+  {
+    "source": "/gateway#multiple-gateways-same-host",
+    "target": "/gateway#multiple-gateways-same-host"
+  },
+  {
+    "source": "install sanity",
+    "target": "安装完整性检查"
+  },
+  {
+    "source": "get unstuck",
+    "target": "解决问题"
+  },
+  {
+    "source": "troubleshooting",
+    "target": "故障排除"
+  },
+  {
+    "source": "FAQ",
+    "target": "常见问题"
+  },
+  {
+    "source": "Ollama Web Search",
+    "target": "Ollama Web 搜索"
+  },
+  {
+    "source": "onboarding",
+    "target": "新手引导"
+  },
+  {
+    "source": "Onboarding",
+    "target": "新手引导"
+  },
+  {
+    "source": "wizard",
+    "target": "向导"
+  },
+  {
+    "source": "environment variables",
+    "target": "环境变量"
+  },
+  {
+    "source": "environment variable",
+    "target": "环境变量"
+  },
+  {
+    "source": "env vars",
+    "target": "环境变量"
+  },
+  {
+    "source": "env var",
+    "target": "环境变量"
+  },
+  {
+    "source": "Plugin SDK",
+    "target": "插件 SDK"
+  },
+  {
+    "source": "Plugin SDK Overview",
+    "target": "插件 SDK 概览"
+  },
+  {
+    "source": "SDK Overview",
+    "target": "SDK 概览"
+  },
+  {
+    "source": "Plugin Entry Points",
+    "target": "插件入口点"
+  },
+  {
+    "source": "Entry Points",
+    "target": "入口点"
+  },
+  {
+    "source": "Plugin Runtime",
+    "target": "插件运行时"
+  },
+  {
+    "source": "Runtime",
+    "target": "运行时"
+  },
+  {
+    "source": "Plugin Setup",
+    "target": "插件设置"
+  },
+  {
+    "source": "Setup",
+    "target": "设置"
+  },
+  {
+    "source": "Channel Plugin SDK",
+    "target": "渠道插件 SDK"
+  },
+  {
+    "source": "Channel Plugins",
+    "target": "渠道插件"
+  },
+  {
+    "source": "Provider Plugin SDK",
+    "target": "提供商插件 SDK"
+  },
+  {
+    "source": "Provider Plugins",
+    "target": "提供商插件"
+  },
+  {
+    "source": "Plugin SDK Testing",
+    "target": "插件 SDK 测试"
+  },
+  {
+    "source": "Testing",
+    "target": "测试"
+  },
+  {
+    "source": "/gateway/configuration#strict-validation",
+    "target": "/gateway/configuration#strict-validation"
+  },
+  {
+    "source": "/gateway/configuration#config-hot-reload",
+    "target": "/gateway/configuration#config-hot-reload"
+  },
+  {
+    "source": "/cli/config",
+    "target": "/cli/config"
+  }
+]
--- a/openclaw/docs/.i18n/id-navigation.json
+++ b/openclaw/docs/.i18n/id-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "id",
+  "tabs": [
+    {
+      "tab": "Mulai",
+      "groups": [
+        {
+          "group": "Ringkasan",
+          "pages": ["id/index"]
+        },
+        {
+          "group": "Langkah pertama",
+          "pages": ["id/start/getting-started", "id/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/it-navigation.json
+++ b/openclaw/docs/.i18n/it-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "it",
+  "tabs": [
+    {
+      "tab": "Inizia",
+      "groups": [
+        {
+          "group": "Panoramica",
+          "pages": ["it/index"]
+        },
+        {
+          "group": "Primi passi",
+          "pages": ["it/start/getting-started", "it/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/ja-navigation.json
+++ b/openclaw/docs/.i18n/ja-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "ja",
+  "tabs": [
+    {
+      "tab": "はじめに",
+      "groups": [
+        {
+          "group": "概要",
+          "pages": ["ja-JP/index"]
+        },
+        {
+          "group": "初回セットアップ",
+          "pages": ["ja-JP/start/getting-started", "ja-JP/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/ko-navigation.json
+++ b/openclaw/docs/.i18n/ko-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "ko",
+  "tabs": [
+    {
+      "tab": "시작하기",
+      "groups": [
+        {
+          "group": "개요",
+          "pages": ["ko/index"]
+        },
+        {
+          "group": "첫 단계",
+          "pages": ["ko/start/getting-started", "ko/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/pl-navigation.json
+++ b/openclaw/docs/.i18n/pl-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "pl",
+  "tabs": [
+    {
+      "tab": "Start",
+      "groups": [
+        {
+          "group": "Przeglad",
+          "pages": ["pl/index"]
+        },
+        {
+          "group": "Pierwsze kroki",
+          "pages": ["pl/start/getting-started", "pl/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/pt-BR-navigation.json
+++ b/openclaw/docs/.i18n/pt-BR-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "pt-BR",
+  "tabs": [
+    {
+      "tab": "Começar",
+      "groups": [
+        {
+          "group": "Visão geral",
+          "pages": ["pt-BR/index"]
+        },
+        {
+          "group": "Primeiros passos",
+          "pages": ["pt-BR/start/getting-started", "pt-BR/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/tr-navigation.json
+++ b/openclaw/docs/.i18n/tr-navigation.json
@ -0,0 +1,18 @@
+{
+  "language": "tr",
+  "tabs": [
+    {
+      "tab": "Baslangic",
+      "groups": [
+        {
+          "group": "Genel bakis",
+          "pages": ["tr/index"]
+        },
+        {
+          "group": "Ilk adimlar",
+          "pages": ["tr/start/getting-started", "tr/start/wizard"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/.i18n/zh-Hans-navigation.json
+++ b/openclaw/docs/.i18n/zh-Hans-navigation.json
@ -0,0 +1,544 @@
+{
+  "language": "zh-Hans",
+  "tabs": [
+    {
+      "tab": "快速开始",
+      "groups": [
+        {
+          "group": "首页",
+          "pages": ["zh-CN/index"]
+        },
+        {
+          "group": "概览",
+          "pages": ["zh-CN/start/showcase"]
+        },
+        {
+          "group": "核心概念",
+          "pages": ["zh-CN/concepts/features"]
+        },
+        {
+          "group": "第一步",
+          "pages": ["zh-CN/start/getting-started", "zh-CN/start/wizard", "zh-CN/start/onboarding"]
+        },
+        {
+          "group": "指南",
+          "pages": ["zh-CN/start/openclaw"]
+        }
+      ]
+    },
+    {
+      "tab": "安装",
+      "groups": [
+        {
+          "group": "安装概览",
+          "pages": ["zh-CN/install/index", "zh-CN/install/installer"]
+        },
+        {
+          "group": "安装方式",
+          "pages": [
+            "zh-CN/install/docker",
+            "zh-CN/install/nix",
+            "zh-CN/install/ansible",
+            "zh-CN/install/bun"
+          ]
+        },
+        {
+          "group": "维护",
+          "pages": ["zh-CN/install/updating", "zh-CN/install/migrating", "zh-CN/install/uninstall"]
+        },
+        {
+          "group": "托管与部署",
+          "pages": [
+            "zh-CN/vps",
+            "zh-CN/install/fly",
+            "zh-CN/install/hetzner",
+            "zh-CN/install/gcp",
+            "zh-CN/install/macos-vm",
+            "zh-CN/install/exe-dev",
+            "zh-CN/install/railway",
+            "zh-CN/install/render",
+            "zh-CN/install/northflank"
+          ]
+        },
+        {
+          "group": "高级",
+          "pages": ["zh-CN/install/development-channels"]
+        }
+      ]
+    },
+    {
+      "tab": "消息渠道",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/channels/index"]
+        },
+        {
+          "group": "消息平台",
+          "pages": [
+            "zh-CN/channels/bluebubbles",
+            "zh-CN/channels/discord",
+            "zh-CN/channels/feishu",
+            "zh-CN/channels/grammy",
+            "zh-CN/channels/googlechat",
+            "zh-CN/channels/imessage",
+            "zh-CN/channels/line",
+            "zh-CN/channels/matrix",
+            "zh-CN/channels/mattermost",
+            "zh-CN/channels/msteams",
+            "zh-CN/channels/nextcloud-talk",
+            "zh-CN/channels/nostr",
+            "zh-CN/channels/signal",
+            "zh-CN/channels/slack",
+            "zh-CN/channels/telegram",
+            "zh-CN/channels/tlon",
+            "zh-CN/channels/twitch",
+            "zh-CN/channels/whatsapp",
+            "zh-CN/channels/zalo",
+            "zh-CN/channels/zalouser"
+          ]
+        },
+        {
+          "group": "配置",
+          "pages": [
+            "zh-CN/channels/pairing",
+            "zh-CN/channels/group-messages",
+            "zh-CN/channels/groups",
+            "zh-CN/channels/broadcast-groups",
+            "zh-CN/channels/channel-routing",
+            "zh-CN/channels/location",
+            "zh-CN/channels/troubleshooting"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "代理",
+      "groups": [
+        {
+          "group": "基础",
+          "pages": [
+            "zh-CN/pi",
+            "zh-CN/concepts/architecture",
+            "zh-CN/concepts/agent",
+            "zh-CN/concepts/agent-loop",
+            "zh-CN/concepts/system-prompt",
+            "zh-CN/concepts/context",
+            "zh-CN/concepts/agent-workspace",
+            "zh-CN/concepts/oauth"
+          ]
+        },
+        {
+          "group": "引导",
+          "pages": ["zh-CN/start/bootstrapping"]
+        },
+        {
+          "group": "会话与记忆",
+          "pages": [
+            "zh-CN/concepts/session",
+            "zh-CN/concepts/session-pruning",
+            "zh-CN/concepts/session-tool",
+            "zh-CN/concepts/memory",
+            "zh-CN/concepts/compaction"
+          ]
+        },
+        {
+          "group": "多代理",
+          "pages": ["zh-CN/concepts/multi-agent", "zh-CN/concepts/presence"]
+        },
+        {
+          "group": "消息与投递",
+          "pages": [
+            "zh-CN/concepts/messages",
+            "zh-CN/concepts/streaming",
+            "zh-CN/concepts/retry",
+            "zh-CN/concepts/queue"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "工具",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/tools/index"]
+        },
+        {
+          "group": "内置工具",
+          "pages": [
+            "zh-CN/tools/apply-patch",
+            "zh-CN/brave-search",
+            "zh-CN/tools/elevated",
+            "zh-CN/tools/exec",
+            "zh-CN/tools/exec-approvals",
+            "zh-CN/tools/firecrawl",
+            "zh-CN/tools/llm-task",
+            "zh-CN/tools/lobster",
+            "zh-CN/perplexity",
+            "zh-CN/tools/reactions",
+            "zh-CN/tools/thinking",
+            "zh-CN/tools/web"
+          ]
+        },
+        {
+          "group": "浏览器",
+          "pages": [
+            "zh-CN/tools/browser",
+            "zh-CN/tools/browser-login",
+            "zh-CN/tools/browser-linux-troubleshooting"
+          ]
+        },
+        {
+          "group": "代理协作",
+          "pages": [
+            "zh-CN/tools/agent-send",
+            "zh-CN/tools/subagents",
+            "zh-CN/tools/multi-agent-sandbox-tools"
+          ]
+        },
+        {
+          "group": "技能",
+          "pages": [
+            "zh-CN/tools/creating-skills",
+            "zh-CN/tools/slash-commands",
+            "zh-CN/tools/skills",
+            "zh-CN/tools/skills-config",
+            "zh-CN/tools/clawhub",
+            "zh-CN/tools/plugin"
+          ]
+        },
+        {
+          "group": "扩展",
+          "pages": [
+            "zh-CN/plugins/voice-call",
+            "zh-CN/plugins/zalouser",
+            "zh-CN/plugins/manifest",
+            "zh-CN/plugins/agent-tools",
+            "zh-CN/prose"
+          ]
+        },
+        {
+          "group": "自动化与任务",
+          "pages": ["zh-CN/automation/hooks", "zh-CN/automation/cron-jobs"]
+        },
+        {
+          "group": "媒体与设备",
+          "pages": [
+            "zh-CN/nodes/index",
+            "zh-CN/nodes/troubleshooting",
+            "zh-CN/nodes/media-understanding",
+            "zh-CN/nodes/images",
+            "zh-CN/nodes/audio",
+            "zh-CN/nodes/camera",
+            "zh-CN/nodes/talk",
+            "zh-CN/nodes/voicewake",
+            "zh-CN/nodes/location-command",
+            "zh-CN/tts"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "模型",
+      "groups": [
+        {
+          "group": "概览",
+          "pages": ["zh-CN/providers/index", "zh-CN/providers/models"]
+        },
+        {
+          "group": "模型概念",
+          "pages": ["zh-CN/concepts/models"]
+        },
+        {
+          "group": "配置",
+          "pages": ["zh-CN/concepts/model-providers", "zh-CN/concepts/model-failover"]
+        },
+        {
+          "group": "提供商",
+          "pages": [
+            "zh-CN/providers/anthropic",
+            "zh-CN/providers/bedrock",
+            "zh-CN/providers/claude-max-api-proxy",
+            "zh-CN/providers/deepgram",
+            "zh-CN/providers/github-copilot",
+            "zh-CN/providers/glm",
+            "zh-CN/providers/moonshot",
+            "zh-CN/providers/minimax",
+            "zh-CN/providers/opencode",
+            "zh-CN/providers/ollama",
+            "zh-CN/providers/openai",
+            "zh-CN/providers/openrouter",
+            "zh-CN/providers/qianfan",
+            "zh-CN/providers/qwen",
+            "zh-CN/providers/synthetic",
+            "zh-CN/providers/venice",
+            "zh-CN/providers/vercel-ai-gateway",
+            "zh-CN/providers/xiaomi",
+            "zh-CN/providers/zai"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "平台",
+      "groups": [
+        {
+          "group": "平台概览",
+          "pages": [
+            "zh-CN/platforms/index",
+            "zh-CN/platforms/macos",
+            "zh-CN/platforms/linux",
+            "zh-CN/platforms/windows",
+            "zh-CN/platforms/android",
+            "zh-CN/platforms/ios",
+            "zh-CN/platforms/digitalocean",
+            "zh-CN/platforms/oracle",
+            "zh-CN/platforms/raspberry-pi"
+          ]
+        },
+        {
+          "group": "macOS 配套应用",
+          "pages": [
+            "zh-CN/platforms/mac/dev-setup",
+            "zh-CN/platforms/mac/menu-bar",
+            "zh-CN/platforms/mac/voicewake",
+            "zh-CN/platforms/mac/voice-overlay",
+            "zh-CN/platforms/mac/webchat",
+            "zh-CN/platforms/mac/canvas",
+            "zh-CN/platforms/mac/child-process",
+            "zh-CN/platforms/mac/health",
+            "zh-CN/platforms/mac/icon",
+            "zh-CN/platforms/mac/logging",
+            "zh-CN/platforms/mac/permissions",
+            "zh-CN/platforms/mac/remote",
+            "zh-CN/platforms/mac/signing",
+            "zh-CN/platforms/mac/bundled-gateway",
+            "zh-CN/platforms/mac/xpc",
+            "zh-CN/platforms/mac/skills",
+            "zh-CN/platforms/mac/peekaboo"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "网关与运维",
+      "groups": [
+        {
+          "group": "网关",
+          "pages": [
+            "zh-CN/gateway/index",
+            {
+              "group": "配置与运维",
+              "pages": [
+                "zh-CN/gateway/configuration",
+                "zh-CN/gateway/configuration-examples",
+                "zh-CN/gateway/authentication",
+                "zh-CN/gateway/health",
+                "zh-CN/gateway/heartbeat",
+                "zh-CN/gateway/doctor",
+                "zh-CN/gateway/logging",
+                "zh-CN/gateway/gateway-lock",
+                "zh-CN/gateway/background-process",
+                "zh-CN/gateway/multiple-gateways",
+                "zh-CN/gateway/troubleshooting"
+              ]
+            },
+            {
+              "group": "安全与沙箱",
+              "pages": [
+                "zh-CN/gateway/security/index",
+                "zh-CN/gateway/sandboxing",
+                "zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated"
+              ]
+            },
+            {
+              "group": "协议与 API",
+              "pages": [
+                "zh-CN/gateway/protocol",
+                "zh-CN/gateway/bridge-protocol",
+                "zh-CN/gateway/openai-http-api",
+                "zh-CN/gateway/openresponses-http-api",
+                "zh-CN/gateway/tools-invoke-http-api",
+                "zh-CN/gateway/cli-backends",
+                "zh-CN/gateway/local-models"
+              ]
+            },
+            {
+              "group": "网络与发现",
+              "pages": [
+                "zh-CN/gateway/network-model",
+                "zh-CN/gateway/pairing",
+                "zh-CN/gateway/discovery",
+                "zh-CN/gateway/bonjour"
+              ]
+            }
+          ]
+        },
+        {
+          "group": "远程访问",
+          "pages": [
+            "zh-CN/gateway/remote",
+            "zh-CN/gateway/remote-gateway-readme",
+            "zh-CN/gateway/tailscale"
+          ]
+        },
+        {
+          "group": "运维专题",
+          "pages": ["zh-CN/network", "zh-CN/logging"]
+        },
+        {
+          "group": "安全",
+          "pages": ["zh-CN/security/formal-verification"]
+        },
+        {
+          "group": "Web 界面",
+          "pages": [
+            "zh-CN/web/index",
+            "zh-CN/web/control-ui",
+            "zh-CN/web/dashboard",
+            "zh-CN/web/webchat",
+            "zh-CN/web/tui"
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "参考",
+      "groups": [
+        {
+          "group": "CLI 命令",
+          "pages": [
+            "zh-CN/cli/index",
+            "zh-CN/cli/acp",
+            "zh-CN/cli/agent",
+            "zh-CN/cli/agents",
+            "zh-CN/cli/approvals",
+            "zh-CN/cli/browser",
+            "zh-CN/cli/channels",
+            "zh-CN/cli/config",
+            "zh-CN/cli/configure",
+            "zh-CN/cli/cron",
+            "zh-CN/cli/dashboard",
+            "zh-CN/cli/devices",
+            "zh-CN/cli/directory",
+            "zh-CN/cli/dns",
+            "zh-CN/cli/docs",
+            "zh-CN/cli/doctor",
+            "zh-CN/cli/gateway",
+            "zh-CN/cli/health",
+            "zh-CN/cli/hooks",
+            "zh-CN/cli/logs",
+            "zh-CN/cli/memory",
+            "zh-CN/cli/message",
+            "zh-CN/cli/models",
+            "zh-CN/cli/node",
+            "zh-CN/cli/nodes",
+            "zh-CN/cli/onboard",
+            "zh-CN/cli/pairing",
+            "zh-CN/cli/plugins",
+            "zh-CN/cli/reset",
+            "zh-CN/cli/sandbox",
+            "zh-CN/cli/security",
+            "zh-CN/cli/sessions",
+            "zh-CN/cli/setup",
+            "zh-CN/cli/skills",
+            "zh-CN/cli/status",
+            "zh-CN/cli/system",
+            "zh-CN/cli/tui",
+            "zh-CN/cli/uninstall",
+            "zh-CN/cli/update",
+            "zh-CN/cli/voicecall",
+            "zh-CN/cli/webhooks"
+          ]
+        },
+        {
+          "group": "RPC 与 API",
+          "pages": ["zh-CN/reference/rpc", "zh-CN/reference/device-models"]
+        },
+        {
+          "group": "模板",
+          "pages": [
+            "zh-CN/reference/AGENTS.default",
+            "zh-CN/reference/templates/AGENTS",
+            "zh-CN/reference/templates/BOOT",
+            "zh-CN/reference/templates/BOOTSTRAP",
+            "zh-CN/reference/templates/HEARTBEAT",
+            "zh-CN/reference/templates/IDENTITY",
+            "zh-CN/reference/templates/SOUL",
+            "zh-CN/reference/templates/TOOLS",
+            "zh-CN/reference/templates/USER"
+          ]
+        },
+        {
+          "group": "技术参考",
+          "pages": [
+            "zh-CN/reference/wizard",
+            "zh-CN/reference/token-use",
+            "zh-CN/reference/api-usage-costs",
+            "zh-CN/reference/transcript-hygiene",
+            "zh-CN/date-time"
+          ]
+        },
+        {
+          "group": "概念内部机制",
+          "pages": [
+            "zh-CN/concepts/typebox",
+            "zh-CN/concepts/markdown-formatting",
+            "zh-CN/concepts/typing-indicators",
+            "zh-CN/concepts/usage-tracking",
+            "zh-CN/concepts/timezone"
+          ]
+        },
+        {
+          "group": "项目",
+          "pages": ["zh-CN/reference/credits"]
+        },
+        {
+          "group": "发布策略",
+          "pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"]
+        }
+      ]
+    },
+    {
+      "tab": "帮助",
+      "groups": [
+        {
+          "group": "帮助",
+          "pages": ["zh-CN/help/index", "zh-CN/help/troubleshooting", "zh-CN/help/faq"]
+        },
+        {
+          "group": "社区",
+          "pages": ["zh-CN/start/lore"]
+        },
+        {
+          "group": "环境与调试",
+          "pages": [
+            "zh-CN/help/environment",
+            "zh-CN/help/debugging",
+            "zh-CN/help/testing",
+            "zh-CN/help/scripts",
+            "zh-CN/debug/node-issue",
+            "zh-CN/diagnostics/flags"
+          ]
+        },
+        {
+          "group": "Node 运行时",
+          "pages": ["zh-CN/install/node"]
+        },
+        {
+          "group": "压缩机制内部参考",
+          "pages": ["zh-CN/reference/session-management-compaction"]
+        },
+        {
+          "group": "开发者设置",
+          "pages": ["zh-CN/start/setup", "zh-CN/pi-dev"]
+        },
+        {
+          "group": "文档元信息",
+          "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory", "zh-CN/AGENTS"]
+        }
+      ]
+    }
+  ]
+}
--- a/openclaw/docs/AGENTS.md
+++ b/openclaw/docs/AGENTS.md
@ -0,0 +1,28 @@
+# Docs Guide
+
+This directory owns docs authoring, Mintlify link rules, and docs i18n policy.
+
+## Mintlify Rules
+
+- Docs are hosted on Mintlify (`https://docs.openclaw.ai`).
+- Internal doc links in `docs/**/*.md` must stay root-relative with no `.md` or `.mdx` suffix (example: `[Config](/configuration)`).
+- Section cross-references should use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
+- Doc headings should avoid em dashes and apostrophes because Mintlify anchor generation is brittle there.
+- README and other GitHub-rendered docs should keep absolute docs URLs so links work outside Mintlify.
+- Docs content must stay generic: no personal device names, hostnames, or local paths; use placeholders like `user@gateway-host`.
+
+## Docs Content Rules
+
+- For docs, UI copy, and picker lists, order services/providers alphabetically unless the section is explicitly describing runtime order or auto-detection order.
+- Keep bundled plugin naming consistent with the repo-wide plugin terminology rules in the root `AGENTS.md`.
+
+## Docs i18n
+
+- Foreign-language docs are not maintained in this repo. The generated publish output lives in the separate `openclaw/docs` repo (often cloned locally as `../openclaw-docs`).
+- Do not add or edit localized docs under `docs/<locale>/**` here.
+- Treat English docs in this repo plus glossary files as the source of truth.
+- Pipeline: update English docs here, update `docs/.i18n/glossary.<locale>.json` as needed, then let the publish-repo sync and `scripts/docs-i18n` run in `openclaw/docs`.
+- Before rerunning `scripts/docs-i18n`, add glossary entries for any new technical terms, page titles, or short nav labels that must stay in English or use a fixed translation.
+- `pnpm docs:check-i18n-glossary` is the guard for changed English doc titles and short internal doc labels.
+- Translation memory lives in generated `docs/.i18n/*.tm.jsonl` files in the publish repo.
+- See `docs/.i18n/README.md`.
--- a/openclaw/docs/CLAUDE.md
+++ b/openclaw/docs/CLAUDE.md
@ -0,0 +1 @@
+AGENTS.md
--- a/openclaw/docs/assets/install-script.svg
+++ b/openclaw/docs/assets/install-script.svg
--- a/openclaw/docs/assets/macos-onboarding/01-macos-warning.jpeg
+++ b/openclaw/docs/assets/macos-onboarding/01-macos-warning.jpeg
--- a/openclaw/docs/assets/macos-onboarding/02-local-networks.jpeg
+++ b/openclaw/docs/assets/macos-onboarding/02-local-networks.jpeg
--- a/openclaw/docs/assets/macos-onboarding/03-security-notice.png
+++ b/openclaw/docs/assets/macos-onboarding/03-security-notice.png
--- a/openclaw/docs/assets/macos-onboarding/04-choose-gateway.png
+++ b/openclaw/docs/assets/macos-onboarding/04-choose-gateway.png
--- a/openclaw/docs/assets/macos-onboarding/05-permissions.png
+++ b/openclaw/docs/assets/macos-onboarding/05-permissions.png
--- a/openclaw/docs/assets/openclaw-logo-text-dark.png
+++ b/openclaw/docs/assets/openclaw-logo-text-dark.png
--- a/openclaw/docs/assets/openclaw-logo-text-dark.svg
+++ b/openclaw/docs/assets/openclaw-logo-text-dark.svg
--- a/openclaw/docs/assets/openclaw-logo-text.png
+++ b/openclaw/docs/assets/openclaw-logo-text.png
--- a/openclaw/docs/assets/openclaw-logo-text.svg
+++ b/openclaw/docs/assets/openclaw-logo-text.svg
--- a/openclaw/docs/assets/pixel-lobster.svg
+++ b/openclaw/docs/assets/pixel-lobster.svg
@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 16 16" role="img" aria-label="Pixel lobster">
+  <rect width="16" height="16" fill="none"/>
+  <!-- outline -->
+  <g fill="#3a0a0d">
+    <rect x="1" y="5" width="1" height="3"/>
+    <rect x="2" y="4" width="1" height="1"/>
+    <rect x="2" y="8" width="1" height="1"/>
+    <rect x="3" y="3" width="1" height="1"/>
+    <rect x="3" y="9" width="1" height="1"/>
+    <rect x="4" y="2" width="1" height="1"/>
+    <rect x="4" y="10" width="1" height="1"/>
+    <rect x="5" y="2" width="6" height="1"/>
+    <rect x="11" y="2" width="1" height="1"/>
+    <rect x="12" y="3" width="1" height="1"/>
+    <rect x="12" y="9" width="1" height="1"/>
+    <rect x="13" y="4" width="1" height="1"/>
+    <rect x="13" y="8" width="1" height="1"/>
+    <rect x="14" y="5" width="1" height="3"/>
+    <rect x="5" y="11" width="6" height="1"/>
+    <rect x="4" y="12" width="1" height="1"/>
+    <rect x="11" y="12" width="1" height="1"/>
+    <rect x="3" y="13" width="1" height="1"/>
+    <rect x="12" y="13" width="1" height="1"/>
+    <rect x="5" y="14" width="6" height="1"/>
+  </g>
+
+  <!-- body -->
+  <g fill="#ff4f40">
+    <rect x="5" y="3" width="6" height="1"/>
+    <rect x="4" y="4" width="8" height="1"/>
+    <rect x="3" y="5" width="10" height="1"/>
+    <rect x="3" y="6" width="10" height="1"/>
+    <rect x="3" y="7" width="10" height="1"/>
+    <rect x="4" y="8" width="8" height="1"/>
+    <rect x="5" y="9" width="6" height="1"/>
+    <rect x="5" y="12" width="6" height="1"/>
+    <rect x="6" y="13" width="4" height="1"/>
+  </g>
+
+  <!-- claws -->
+  <g fill="#ff775f">
+    <rect x="1" y="6" width="2" height="1"/>
+    <rect x="2" y="5" width="1" height="1"/>
+    <rect x="2" y="7" width="1" height="1"/>
+    <rect x="13" y="6" width="2" height="1"/>
+    <rect x="13" y="5" width="1" height="1"/>
+    <rect x="13" y="7" width="1" height="1"/>
+  </g>
+
+  <!-- eyes -->
+  <g fill="#081016">
+    <rect x="6" y="5" width="1" height="1"/>
+    <rect x="9" y="5" width="1" height="1"/>
+  </g>
+  <g fill="#f5fbff">
+    <rect x="6" y="4" width="1" height="1"/>
+    <rect x="9" y="4" width="1" height="1"/>
+  </g>
+</svg>
+
--- a/openclaw/docs/assets/showcase/agents-ui.jpg
+++ b/openclaw/docs/assets/showcase/agents-ui.jpg
--- a/openclaw/docs/assets/showcase/bambu-cli.png
+++ b/openclaw/docs/assets/showcase/bambu-cli.png
--- a/openclaw/docs/assets/showcase/codexmonitor.png
+++ b/openclaw/docs/assets/showcase/codexmonitor.png
--- a/openclaw/docs/assets/showcase/gohome-grafana.png
+++ b/openclaw/docs/assets/showcase/gohome-grafana.png
--- a/openclaw/docs/assets/showcase/ios-testflight.jpg
+++ b/openclaw/docs/assets/showcase/ios-testflight.jpg
--- a/openclaw/docs/assets/showcase/oura-health.png
+++ b/openclaw/docs/assets/showcase/oura-health.png
--- a/openclaw/docs/assets/showcase/padel-cli.svg
+++ b/openclaw/docs/assets/showcase/padel-cli.svg
@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="420" viewBox="0 0 800 420" role="img" aria-label="padel-cli availability output">
+  <rect width="800" height="420" rx="24" fill="#0b0f14" />
+  <rect x="24" y="24" width="752" height="372" rx="18" fill="#0f172a" stroke="#263246" stroke-width="2" />
+  <text x="48" y="72" fill="#9ca3af" font-size="18" font-family="Fragment Mono, ui-monospace, SFMono-Regular, Menlo, monospace">
+    <tspan x="48" dy="0">$ padel search --location "Barcelona" --date 2026-01-08 --time 18:00-22:00</tspan>
+    <tspan x="48" dy="30" fill="#e5e7eb">Available courts (3):</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">- Vall d'Hebron 19:00 Court 2 (90m) EUR 34</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">- Badalona 20:30 Court 1 (60m) EUR 28</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">- Gracia 21:00 Court 4 (90m) EUR 36</tspan>
+  </text>
+</svg>
--- a/openclaw/docs/assets/showcase/padel-screenshot.jpg
+++ b/openclaw/docs/assets/showcase/padel-screenshot.jpg
--- a/openclaw/docs/assets/showcase/papla-tts.jpg
+++ b/openclaw/docs/assets/showcase/papla-tts.jpg
--- a/openclaw/docs/assets/showcase/pr-review-telegram.jpg
+++ b/openclaw/docs/assets/showcase/pr-review-telegram.jpg
--- a/openclaw/docs/assets/showcase/roborock-screenshot.jpg
+++ b/openclaw/docs/assets/showcase/roborock-screenshot.jpg
--- a/openclaw/docs/assets/showcase/roborock-status.svg
+++ b/openclaw/docs/assets/showcase/roborock-status.svg
@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="420" viewBox="0 0 800 420" role="img" aria-label="GoHome Roborock status output">
+  <rect width="800" height="420" rx="24" fill="#0b0f14" />
+  <rect x="24" y="24" width="752" height="372" rx="18" fill="#111827" stroke="#263246" stroke-width="2" />
+  <text x="48" y="72" fill="#9ca3af" font-size="18" font-family="Fragment Mono, ui-monospace, SFMono-Regular, Menlo, monospace">
+    <tspan x="48" dy="0">$ gohome roborock status --device "Living Room"</tspan>
+    <tspan x="48" dy="30" fill="#e5e7eb">Device: Roborock Q Revo</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">State: cleaning (zone)</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">Battery: 78%</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">Dustbin: 42%</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">Water tank: 61%</tspan>
+    <tspan x="48" dy="28" fill="#e5e7eb">Last clean: 2026-01-06 19:42</tspan>
+  </text>
+</svg>
--- a/openclaw/docs/assets/showcase/roof-camera-sky.jpg
+++ b/openclaw/docs/assets/showcase/roof-camera-sky.jpg
--- a/openclaw/docs/assets/showcase/snag.png
+++ b/openclaw/docs/assets/showcase/snag.png
--- a/openclaw/docs/assets/showcase/tesco-shop.jpg
+++ b/openclaw/docs/assets/showcase/tesco-shop.jpg
--- a/openclaw/docs/assets/showcase/wienerlinien.png
+++ b/openclaw/docs/assets/showcase/wienerlinien.png
--- a/openclaw/docs/assets/showcase/wine-cellar-skill.jpg
+++ b/openclaw/docs/assets/showcase/wine-cellar-skill.jpg
--- a/openclaw/docs/assets/showcase/winix-air-purifier.jpg
+++ b/openclaw/docs/assets/showcase/winix-air-purifier.jpg
--- a/openclaw/docs/assets/showcase/xuezh-pronunciation.jpeg
+++ b/openclaw/docs/assets/showcase/xuezh-pronunciation.jpeg
--- a/openclaw/docs/assets/sponsors/blacksmith-light.svg
+++ b/openclaw/docs/assets/sponsors/blacksmith-light.svg
--- a/openclaw/docs/assets/sponsors/blacksmith.svg
+++ b/openclaw/docs/assets/sponsors/blacksmith.svg
--- a/openclaw/docs/assets/sponsors/convex-light.svg
+++ b/openclaw/docs/assets/sponsors/convex-light.svg
@ -0,0 +1,16 @@
+<svg width="126" height="20" viewBox="0 0 126 20" fill="black" xmlns="http://www.w3.org/2000/svg">
+  <g clip-path="url(#clip0_5_2)">
+    <path d="M3.18483 17.4674C1.30005 15.782 0.357666 13.2908 0.357666 10.0003C0.357666 6.70977 1.31835 4.2186 3.24278 2.53321C5.16415 0.847812 7.79308 0.00350952 11.1265 0.00350952C12.5111 0.00350952 13.7341 0.103028 14.7985 0.308486C15.8629 0.510733 16.8815 0.854231 17.8544 1.34219V6.68088C16.3417 5.92646 14.6246 5.54765 12.7033 5.54765C11.0106 5.54765 9.76021 5.88473 8.95506 6.55889C8.14686 7.23304 7.74429 8.37911 7.74429 10.0003C7.74429 11.5669 8.14076 12.7001 8.93676 13.4C9.72971 14.103 10.9862 14.453 12.7063 14.453C14.527 14.453 16.2563 14.0067 17.8971 13.1175V18.7034C16.0763 19.5669 13.8073 19.9971 11.0899 19.9971C7.70159 19.9971 5.06961 19.1528 3.18483 17.4674Z" />
+    <path d="M19.538 9.99679C19.538 6.73194 20.4224 4.2504 22.1913 2.54896C23.9602 0.847512 26.6257 0 30.1909 0C33.7805 0 36.4644 0.850722 38.2485 2.54896C40.0296 4.24719 40.9201 6.73194 40.9201 9.99679C40.9201 16.6613 37.3427 19.9936 30.1909 19.9936C23.0879 19.9968 19.538 16.6645 19.538 9.99679ZM32.7497 13.3997C33.2743 12.6966 33.5365 11.5634 33.5365 10C33.5365 8.46228 33.2743 7.33547 32.7497 6.61958C32.2251 5.90369 31.3712 5.54735 30.1909 5.54735C29.0381 5.54735 28.2024 5.9069 27.6901 6.61958C27.1777 7.33547 26.9215 8.46228 26.9215 10C26.9215 11.5666 27.1777 12.6998 27.6901 13.3997C28.2024 14.1027 29.035 14.4526 30.1909 14.4526C31.3712 14.4526 32.2221 14.0995 32.7497 13.3997Z" />
+    <path d="M42.6029 0.404494H49.3704L49.5626 1.86196C50.3067 1.32263 51.2552 0.876404 52.408 0.526485C53.5608 0.176565 54.7533 0 55.9854 0C58.2667 0 59.9319 0.5939 60.9841 1.7817C62.0363 2.9695 62.5608 4.80257 62.5608 7.28732V19.5923H55.3328V8.05458C55.3328 7.19101 55.1467 6.57143 54.7747 6.19262C54.4026 5.8138 53.7804 5.62761 52.9082 5.62761C52.3714 5.62761 51.8194 5.75602 51.2552 6.01284C50.691 6.26966 50.2183 6.60032 49.8309 7.00482V19.5923H42.6029V0.404494Z" />
+    <path d="M62.5818 0.404617H70.1178L73.5794 11.6566L77.0409 0.404617H84.5769L77.3855 19.5924H69.7702L62.5818 0.404617Z" />
+    <path d="M86.8523 17.9422C84.6809 16.2279 83.6653 13.252 83.6653 10.0385C83.6653 6.90851 84.4735 4.33066 86.3186 2.54896C88.1637 0.767255 90.9757 0 94.5256 0C97.792 0 100.36 0.796147 102.236 2.38844C104.108 3.98074 105.047 6.15409 105.047 8.9053V12.2665H91.302C91.6436 13.2648 92.0766 13.9872 93.141 14.4334C94.2054 14.8796 95.6907 15.1011 97.5907 15.1011C98.7252 15.1011 99.8841 15.008 101.061 14.8186C101.476 14.7512 102.159 14.6453 102.519 14.565V19.2295C100.723 19.7432 98.3287 20 95.6297 20C91.9973 19.9968 89.0238 19.6565 86.8523 17.9422ZM97.4534 8.13804C97.4534 7.1878 96.4135 5.14286 94.3243 5.14286C92.4396 5.14286 91.1952 7.1557 91.1952 8.13804H97.4534Z" />
+    <path d="M110.723 9.8364L103.955 0.404617H111.799L125.642 19.5924H117.722L114.645 15.3003L111.567 19.5924H103.684L110.723 9.8364Z" />
+    <path d="M117.548 0.404617H125.356L119.363 8.8059L115.398 3.42227L117.548 0.404617Z" />
+  </g>
+  <defs>
+    <clipPath id="clip0_5_2">
+      <rect width="126" height="20" />
+    </clipPath>
+  </defs>
+</svg>
--- a/openclaw/docs/assets/sponsors/convex.svg
+++ b/openclaw/docs/assets/sponsors/convex.svg
@ -0,0 +1,16 @@
+<svg width="126" height="20" viewBox="0 0 126 20" fill="white" xmlns="http://www.w3.org/2000/svg">
+  <g clip-path="url(#clip0_5_2)">
+    <path d="M3.18483 17.4674C1.30005 15.782 0.357666 13.2908 0.357666 10.0003C0.357666 6.70977 1.31835 4.2186 3.24278 2.53321C5.16415 0.847812 7.79308 0.00350952 11.1265 0.00350952C12.5111 0.00350952 13.7341 0.103028 14.7985 0.308486C15.8629 0.510733 16.8815 0.854231 17.8544 1.34219V6.68088C16.3417 5.92646 14.6246 5.54765 12.7033 5.54765C11.0106 5.54765 9.76021 5.88473 8.95506 6.55889C8.14686 7.23304 7.74429 8.37911 7.74429 10.0003C7.74429 11.5669 8.14076 12.7001 8.93676 13.4C9.72971 14.103 10.9862 14.453 12.7063 14.453C14.527 14.453 16.2563 14.0067 17.8971 13.1175V18.7034C16.0763 19.5669 13.8073 19.9971 11.0899 19.9971C7.70159 19.9971 5.06961 19.1528 3.18483 17.4674Z" />
+    <path d="M19.538 9.99679C19.538 6.73194 20.4224 4.2504 22.1913 2.54896C23.9602 0.847512 26.6257 0 30.1909 0C33.7805 0 36.4644 0.850722 38.2485 2.54896C40.0296 4.24719 40.9201 6.73194 40.9201 9.99679C40.9201 16.6613 37.3427 19.9936 30.1909 19.9936C23.0879 19.9968 19.538 16.6645 19.538 9.99679ZM32.7497 13.3997C33.2743 12.6966 33.5365 11.5634 33.5365 10C33.5365 8.46228 33.2743 7.33547 32.7497 6.61958C32.2251 5.90369 31.3712 5.54735 30.1909 5.54735C29.0381 5.54735 28.2024 5.9069 27.6901 6.61958C27.1777 7.33547 26.9215 8.46228 26.9215 10C26.9215 11.5666 27.1777 12.6998 27.6901 13.3997C28.2024 14.1027 29.035 14.4526 30.1909 14.4526C31.3712 14.4526 32.2221 14.0995 32.7497 13.3997Z" />
+    <path d="M42.6029 0.404494H49.3704L49.5626 1.86196C50.3067 1.32263 51.2552 0.876404 52.408 0.526485C53.5608 0.176565 54.7533 0 55.9854 0C58.2667 0 59.9319 0.5939 60.9841 1.7817C62.0363 2.9695 62.5608 4.80257 62.5608 7.28732V19.5923H55.3328V8.05458C55.3328 7.19101 55.1467 6.57143 54.7747 6.19262C54.4026 5.8138 53.7804 5.62761 52.9082 5.62761C52.3714 5.62761 51.8194 5.75602 51.2552 6.01284C50.691 6.26966 50.2183 6.60032 49.8309 7.00482V19.5923H42.6029V0.404494Z" />
+    <path d="M62.5818 0.404617H70.1178L73.5794 11.6566L77.0409 0.404617H84.5769L77.3855 19.5924H69.7702L62.5818 0.404617Z" />
+    <path d="M86.8523 17.9422C84.6809 16.2279 83.6653 13.252 83.6653 10.0385C83.6653 6.90851 84.4735 4.33066 86.3186 2.54896C88.1637 0.767255 90.9757 0 94.5256 0C97.792 0 100.36 0.796147 102.236 2.38844C104.108 3.98074 105.047 6.15409 105.047 8.9053V12.2665H91.302C91.6436 13.2648 92.0766 13.9872 93.141 14.4334C94.2054 14.8796 95.6907 15.1011 97.5907 15.1011C98.7252 15.1011 99.8841 15.008 101.061 14.8186C101.476 14.7512 102.159 14.6453 102.519 14.565V19.2295C100.723 19.7432 98.3287 20 95.6297 20C91.9973 19.9968 89.0238 19.6565 86.8523 17.9422ZM97.4534 8.13804C97.4534 7.1878 96.4135 5.14286 94.3243 5.14286C92.4396 5.14286 91.1952 7.1557 91.1952 8.13804H97.4534Z" />
+    <path d="M110.723 9.8364L103.955 0.404617H111.799L125.642 19.5924H117.722L114.645 15.3003L111.567 19.5924H103.684L110.723 9.8364Z" />
+    <path d="M117.548 0.404617H125.356L119.363 8.8059L115.398 3.42227L117.548 0.404617Z" />
+  </g>
+  <defs>
+    <clipPath id="clip0_5_2">
+      <rect width="126" height="20" />
+    </clipPath>
+  </defs>
+</svg>
--- a/openclaw/docs/assets/sponsors/github-light.svg
+++ b/openclaw/docs/assets/sponsors/github-light.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#111827" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>
--- a/openclaw/docs/assets/sponsors/github.svg
+++ b/openclaw/docs/assets/sponsors/github.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="#fff" aria-hidden="true">
+  <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
+</svg>
--- a/openclaw/docs/assets/sponsors/nvidia-dark.svg
+++ b/openclaw/docs/assets/sponsors/nvidia-dark.svg
@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 164 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path d="M160.352,24.069L160.352,23.62L160.64,23.62C160.797,23.62 161.011,23.632 161.011,23.824C161.011,24.032 160.901,24.069 160.715,24.069L160.352,24.069M160.352,24.384L160.544,24.384L160.991,25.168L161.481,25.168L160.987,24.352C161.242,24.333 161.452,24.212 161.452,23.868C161.452,23.441 161.157,23.303 160.659,23.303L159.938,23.303L159.938,25.168L160.352,25.168L160.352,24.384M162.45,24.238C162.45,23.143 161.599,22.508 160.65,22.508C159.695,22.508 158.845,23.143 158.845,24.238C158.845,25.333 159.695,25.971 160.65,25.971C161.598,25.971 162.45,25.333 162.45,24.238M161.93,24.238C161.93,25.036 161.343,25.572 160.65,25.572L160.65,25.566C159.937,25.572 159.361,25.036 159.361,24.238C159.361,23.441 159.938,22.907 160.65,22.907C161.344,22.907 161.93,23.441 161.93,24.238" style="fill:white;"/>
+        <path d="M96.374,5.707L96.376,25.367L101.928,25.367L101.928,5.707L96.374,5.707ZM52.697,5.681L52.697,25.367L58.3,25.367L58.3,10.086L62.67,10.1C64.107,10.1 65.1,10.445 65.793,11.184C66.672,12.12 67.03,13.628 67.03,16.389L67.03,25.367L72.457,25.367L72.457,14.49C72.457,6.727 67.509,5.68 62.668,5.68L52.698,5.68L52.697,5.681ZM105.314,5.708L105.314,25.367L114.32,25.367C119.118,25.367 120.684,24.569 122.377,22.78C123.575,21.524 124.348,18.766 124.348,15.753C124.348,12.99 123.693,10.525 122.551,8.99C120.494,6.245 117.531,5.708 113.106,5.708L105.314,5.708ZM110.822,9.988L113.209,9.988C116.672,9.988 118.912,11.544 118.912,15.579C118.912,19.616 116.672,21.171 113.209,21.171L110.822,21.171L110.822,9.988ZM88.369,5.708L83.735,21.288L79.295,5.709L73.302,5.708L79.642,25.367L87.645,25.367L94.036,5.708L88.369,5.708ZM126.932,25.367L132.485,25.367L132.485,5.709L126.93,5.708L126.932,25.367ZM142.496,5.715L134.743,25.36L140.218,25.36L141.445,21.888L150.62,21.888L151.781,25.36L157.725,25.36L149.913,5.714L142.496,5.715ZM146.1,9.3L149.464,18.504L142.631,18.504L146.101,9.3L146.1,9.3Z" style="fill:white;"/>
+        <path d="M16.889,8.985L16.889,6.28C17.151,6.26 17.417,6.247 17.687,6.238C25.087,6.006 29.942,12.597 29.942,12.597C29.942,12.597 24.698,19.879 19.076,19.879C18.333,19.882 17.594,19.764 16.889,19.529L16.889,11.325C19.769,11.673 20.349,12.945 22.081,15.833L25.933,12.585C25.933,12.585 23.121,8.897 18.381,8.897C17.866,8.897 17.373,8.933 16.889,8.985ZM16.889,0.047L16.889,4.09C17.154,4.069 17.42,4.052 17.687,4.042C27.977,3.696 34.682,12.482 34.682,12.482C34.682,12.482 26.982,21.846 18.959,21.846C18.224,21.846 17.535,21.778 16.889,21.663L16.889,24.161C17.442,24.231 18.015,24.273 18.613,24.273C26.078,24.273 31.477,20.461 36.705,15.948C37.572,16.642 41.121,18.331 41.85,19.071C36.879,23.231 25.295,26.586 18.727,26.586C18.113,26.584 17.5,26.552 16.889,26.49L16.889,30L45.264,30L45.264,0.047L16.889,0.047ZM16.889,19.529L16.889,21.662C9.984,20.432 8.067,13.254 8.067,13.254C8.067,13.254 11.383,9.58 16.889,8.985L16.889,11.325L16.878,11.324C13.988,10.977 11.731,13.677 11.731,13.677C11.731,13.677 12.996,18.221 16.889,19.529ZM4.625,12.943C4.625,12.943 8.717,6.903 16.889,6.28L16.889,4.088C7.838,4.815 0,12.48 0,12.48C0,12.48 4.439,25.313 16.889,26.488L16.889,24.16C7.753,23.011 4.625,12.943 4.625,12.943Z" style="fill:rgb(118,185,0);"/>
+    </g>
+</svg>
--- a/openclaw/docs/assets/sponsors/nvidia.svg
+++ b/openclaw/docs/assets/sponsors/nvidia.svg
@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 164 30" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g>
+        <path d="M160.352,24.069L160.352,23.62L160.64,23.62C160.797,23.62 161.011,23.632 161.011,23.824C161.011,24.032 160.901,24.069 160.715,24.069L160.352,24.069M160.352,24.384L160.544,24.384L160.991,25.168L161.481,25.168L160.987,24.352C161.242,24.333 161.452,24.212 161.452,23.868C161.452,23.441 161.157,23.303 160.659,23.303L159.938,23.303L159.938,25.168L160.352,25.168L160.352,24.384M162.45,24.238C162.45,23.143 161.599,22.508 160.65,22.508C159.695,22.508 158.845,23.143 158.845,24.238C158.845,25.333 159.695,25.971 160.65,25.971C161.598,25.971 162.45,25.333 162.45,24.238M161.93,24.238C161.93,25.036 161.343,25.572 160.65,25.572L160.65,25.566C159.937,25.572 159.361,25.036 159.361,24.238C159.361,23.441 159.938,22.907 160.65,22.907C161.344,22.907 161.93,23.441 161.93,24.238" style="fill:black;"/>
+        <path d="M96.374,5.707L96.376,25.367L101.928,25.367L101.928,5.707L96.374,5.707ZM52.697,5.681L52.697,25.367L58.3,25.367L58.3,10.086L62.67,10.1C64.107,10.1 65.1,10.445 65.793,11.184C66.672,12.12 67.03,13.628 67.03,16.389L67.03,25.367L72.457,25.367L72.457,14.49C72.457,6.727 67.509,5.68 62.668,5.68L52.698,5.68L52.697,5.681ZM105.314,5.708L105.314,25.367L114.32,25.367C119.118,25.367 120.684,24.569 122.377,22.78C123.575,21.524 124.348,18.766 124.348,15.753C124.348,12.99 123.693,10.525 122.551,8.99C120.494,6.245 117.531,5.708 113.106,5.708L105.314,5.708ZM110.822,9.988L113.209,9.988C116.672,9.988 118.912,11.544 118.912,15.579C118.912,19.616 116.672,21.171 113.209,21.171L110.822,21.171L110.822,9.988ZM88.369,5.708L83.735,21.288L79.295,5.709L73.302,5.708L79.642,25.367L87.645,25.367L94.036,5.708L88.369,5.708ZM126.932,25.367L132.485,25.367L132.485,5.709L126.93,5.708L126.932,25.367ZM142.496,5.715L134.743,25.36L140.218,25.36L141.445,21.888L150.62,21.888L151.781,25.36L157.725,25.36L149.913,5.714L142.496,5.715ZM146.1,9.3L149.464,18.504L142.631,18.504L146.101,9.3L146.1,9.3Z" style="fill:black;"/>
+        <path d="M16.889,8.985L16.889,6.28C17.151,6.26 17.417,6.247 17.687,6.238C25.087,6.006 29.942,12.597 29.942,12.597C29.942,12.597 24.698,19.879 19.076,19.879C18.333,19.882 17.594,19.764 16.889,19.529L16.889,11.325C19.769,11.673 20.349,12.945 22.081,15.833L25.933,12.585C25.933,12.585 23.121,8.897 18.381,8.897C17.866,8.897 17.373,8.933 16.889,8.985ZM16.889,0.047L16.889,4.09C17.154,4.069 17.42,4.052 17.687,4.042C27.977,3.696 34.682,12.482 34.682,12.482C34.682,12.482 26.982,21.846 18.959,21.846C18.224,21.846 17.535,21.778 16.889,21.663L16.889,24.161C17.442,24.231 18.015,24.273 18.613,24.273C26.078,24.273 31.477,20.461 36.705,15.948C37.572,16.642 41.121,18.331 41.85,19.071C36.879,23.231 25.295,26.586 18.727,26.586C18.113,26.584 17.5,26.552 16.889,26.49L16.889,30L45.264,30L45.264,0.047L16.889,0.047ZM16.889,19.529L16.889,21.662C9.984,20.432 8.067,13.254 8.067,13.254C8.067,13.254 11.383,9.58 16.889,8.985L16.889,11.325L16.878,11.324C13.988,10.977 11.731,13.677 11.731,13.677C11.731,13.677 12.996,18.221 16.889,19.529ZM4.625,12.943C4.625,12.943 8.717,6.903 16.889,6.28L16.889,4.088C7.838,4.815 0,12.48 0,12.48C0,12.48 4.439,25.313 16.889,26.488L16.889,24.16C7.753,23.011 4.625,12.943 4.625,12.943Z" style="fill:rgb(118,185,0);"/>
+    </g>
+</svg>
--- a/openclaw/docs/assets/sponsors/openai-light.svg
+++ b/openclaw/docs/assets/sponsors/openai-light.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="black">
+  <path d="M22.282 9.821a5.985 5.985 0 0 0-.516-4.91 6.046 6.046 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a5.985 5.985 0 0 0-3.998 2.9 6.046 6.046 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.051 6.051 0 0 0 6.515 2.9A5.985 5.985 0 0 0 13.26 24a6.056 6.056 0 0 0 5.772-4.206 5.99 5.99 0 0 0 3.997-2.9 6.056 6.056 0 0 0-.747-7.073zM13.26 22.43a4.476 4.476 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.795.795 0 0 0 .392-.681v-6.737l2.02 1.168a.071.071 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494zM3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.771.771 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646zM2.34 7.896a4.485 4.485 0 0 1 2.366-1.973V11.6a.766.766 0 0 0 .388.676l5.815 3.355-2.02 1.168a.076.076 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855l-5.833-3.387L15.119 7.2a.076.076 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667zm2.01-3.023l-.141-.085-4.774-2.782a.776.776 0 0 0-.785 0L9.409 9.23V6.897a.066.066 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135l-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.795.795 0 0 0-.393.681zm1.097-2.365l2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5z"/>
+</svg>
--- a/openclaw/docs/assets/sponsors/openai.svg
+++ b/openclaw/docs/assets/sponsors/openai.svg
@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="white">
+  <path d="M22.282 9.821a5.985 5.985 0 0 0-.516-4.91 6.046 6.046 0 0 0-6.51-2.9A6.065 6.065 0 0 0 4.981 4.18a5.985 5.985 0 0 0-3.998 2.9 6.046 6.046 0 0 0 .743 7.097 5.98 5.98 0 0 0 .51 4.911 6.051 6.051 0 0 0 6.515 2.9A5.985 5.985 0 0 0 13.26 24a6.056 6.056 0 0 0 5.772-4.206 5.99 5.99 0 0 0 3.997-2.9 6.056 6.056 0 0 0-.747-7.073zM13.26 22.43a4.476 4.476 0 0 1-2.876-1.04l.141-.081 4.779-2.758a.795.795 0 0 0 .392-.681v-6.737l2.02 1.168a.071.071 0 0 1 .038.052v5.583a4.504 4.504 0 0 1-4.494 4.494zM3.6 18.304a4.47 4.47 0 0 1-.535-3.014l.142.085 4.783 2.759a.771.771 0 0 0 .78 0l5.843-3.369v2.332a.08.08 0 0 1-.033.062L9.74 19.95a4.5 4.5 0 0 1-6.14-1.646zM2.34 7.896a4.485 4.485 0 0 1 2.366-1.973V11.6a.766.766 0 0 0 .388.676l5.815 3.355-2.02 1.168a.076.076 0 0 1-.071 0l-4.83-2.786A4.504 4.504 0 0 1 2.34 7.872zm16.597 3.855l-5.833-3.387L15.119 7.2a.076.076 0 0 1 .071 0l4.83 2.791a4.494 4.494 0 0 1-.676 8.105v-5.678a.79.79 0 0 0-.407-.667zm2.01-3.023l-.141-.085-4.774-2.782a.776.776 0 0 0-.785 0L9.409 9.23V6.897a.066.066 0 0 1 .028-.061l4.83-2.787a4.5 4.5 0 0 1 6.68 4.66zm-12.64 4.135l-2.02-1.164a.08.08 0 0 1-.038-.057V6.075a4.5 4.5 0 0 1 7.375-3.453l-.142.08L8.704 5.46a.795.795 0 0 0-.393.681zm1.097-2.365l2.602-1.5 2.607 1.5v2.999l-2.597 1.5-2.607-1.5z"/>
+</svg>
--- a/openclaw/docs/assets/sponsors/vercel-light.svg
+++ b/openclaw/docs/assets/sponsors/vercel-light.svg
@ -0,0 +1,5 @@
+<svg width="256" height="51" viewBox="0 0 256 50.875" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g transform="scale(0.125)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M467.444 406.809L233.722 0.335938L0 406.809H467.444ZM703.186 388.306L898.51 18.813H814.024L679.286 287.152L544.547 18.813H460.061L655.385 388.306H703.186ZM2034.31 18.813V388.307H1964.37V18.813H2034.31ZM1644.98 250.395C1644.98 221.599 1650.99 196.272 1663.01 174.415C1675.03 152.557 1691.79 135.731 1713.28 123.935C1734.77 112.139 1759.91 106.241 1788.69 106.241C1814.19 106.241 1837.14 111.792 1857.54 122.894C1877.94 133.996 1894.15 150.476 1906.17 172.333C1918.19 194.191 1924.39 220.905 1924.75 252.477V268.61H1718.75C1720.2 291.508 1726.94 309.549 1738.96 322.733C1751.35 335.57 1767.93 341.988 1788.69 341.988C1801.8 341.988 1813.83 338.519 1824.75 331.58C1835.68 324.641 1843.88 315.274 1849.34 303.478L1920.93 308.682C1912.18 334.702 1895.79 355.519 1871.75 371.131C1847.7 386.744 1820.02 394.55 1788.69 394.55C1759.91 394.55 1734.77 388.652 1713.28 376.856C1691.79 365.06 1675.03 348.233 1663.01 326.376C1650.99 304.518 1644.98 279.192 1644.98 250.395ZM1852.62 224.375C1850.07 201.823 1842.97 185.344 1831.31 174.935C1819.65 164.18 1805.45 158.802 1788.69 158.802C1769.38 158.802 1753.72 164.527 1741.7 175.976C1729.67 187.425 1722.21 203.558 1719.29 224.375H1852.62ZM1526.96 174.935C1538.62 184.303 1545.9 197.313 1548.82 213.966L1620.94 210.323C1618.39 189.16 1610.93 170.772 1598.54 155.159C1586.15 139.547 1570.13 127.578 1550.45 119.251C1531.15 110.577 1509.84 106.241 1486.52 106.241C1457.74 106.241 1432.61 112.139 1411.11 123.935C1389.62 135.731 1372.86 152.557 1360.84 174.415C1348.82 196.272 1342.81 221.599 1342.81 250.395C1342.81 279.192 1348.82 304.518 1360.84 326.376C1372.86 348.233 1389.62 365.06 1411.11 376.856C1432.61 388.652 1457.74 394.55 1486.52 394.55C1510.56 394.55 1532.42 390.213 1552.09 381.54C1571.77 372.519 1587.79 359.856 1600.18 343.549C1612.57 327.243 1620.03 308.161 1622.58 286.304L1549.91 283.181C1547.36 301.569 1540.25 315.794 1528.6 325.855C1516.94 335.57 1502.91 340.427 1486.52 340.427C1463.94 340.427 1446.45 332.621 1434.06 317.008C1421.68 301.396 1415.49 279.192 1415.49 250.395C1415.49 221.599 1421.68 199.395 1434.06 183.782C1446.45 168.17 1463.94 160.364 1486.52 160.364C1502.19 160.364 1515.66 165.221 1526.96 174.935ZM1172.15 112.473H1237.24L1239.12 165.559C1243.74 150.533 1250.16 138.864 1258.39 130.552C1270.32 118.5 1286.96 112.473 1308.29 112.473H1334.87V169.293H1307.75C1292.56 169.293 1280.09 171.359 1270.32 175.491C1260.92 179.624 1253.69 186.166 1248.63 195.12C1243.93 204.073 1241.58 215.437 1241.58 229.211V388.306H1172.15V112.473ZM871.925 174.415C859.904 196.272 853.893 221.599 853.893 250.395C853.893 279.192 859.904 304.518 871.925 326.376C883.947 348.233 900.704 365.06 922.198 376.856C943.691 388.652 968.827 394.55 997.606 394.55C1028.93 394.55 1056.62 386.744 1080.66 371.131C1104.71 355.519 1121.1 334.702 1129.84 308.682L1058.26 303.478C1052.8 315.274 1044.6 324.641 1033.67 331.58C1022.74 338.519 1010.72 341.988 997.606 341.988C976.841 341.988 960.266 335.57 947.88 322.733C935.858 309.549 929.119 291.508 927.662 268.61H1133.67V252.477C1133.3 220.905 1127.11 194.191 1115.09 172.333C1103.07 150.476 1086.86 133.996 1066.46 122.894C1046.06 111.792 1023.11 106.241 997.606 106.241C968.827 106.241 943.691 112.139 922.198 123.935C900.704 135.731 883.947 152.557 871.925 174.415ZM1040.23 174.935C1051.88 185.344 1058.99 201.823 1061.54 224.375H928.208C931.123 203.558 938.591 187.425 950.612 175.976C962.634 164.527 978.298 158.802 997.606 158.802C1014.36 158.802 1028.57 164.18 1040.23 174.935Z" fill="black"/>
+</g>
+</svg>
--- a/openclaw/docs/assets/sponsors/vercel.svg
+++ b/openclaw/docs/assets/sponsors/vercel.svg
@ -0,0 +1,5 @@
+<svg width="256" height="51" viewBox="0 0 256 50.875" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g transform="scale(0.125)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M467.444 406.809L233.722 0.335938L0 406.809H467.444ZM703.186 388.306L898.51 18.813H814.024L679.286 287.152L544.547 18.813H460.061L655.385 388.306H703.186ZM2034.31 18.813V388.307H1964.37V18.813H2034.31ZM1644.98 250.395C1644.98 221.599 1650.99 196.272 1663.01 174.415C1675.03 152.557 1691.79 135.731 1713.28 123.935C1734.77 112.139 1759.91 106.241 1788.69 106.241C1814.19 106.241 1837.14 111.792 1857.54 122.894C1877.94 133.996 1894.15 150.476 1906.17 172.333C1918.19 194.191 1924.39 220.905 1924.75 252.477V268.61H1718.75C1720.2 291.508 1726.94 309.549 1738.96 322.733C1751.35 335.57 1767.93 341.988 1788.69 341.988C1801.8 341.988 1813.83 338.519 1824.75 331.58C1835.68 324.641 1843.88 315.274 1849.34 303.478L1920.93 308.682C1912.18 334.702 1895.79 355.519 1871.75 371.131C1847.7 386.744 1820.02 394.55 1788.69 394.55C1759.91 394.55 1734.77 388.652 1713.28 376.856C1691.79 365.06 1675.03 348.233 1663.01 326.376C1650.99 304.518 1644.98 279.192 1644.98 250.395ZM1852.62 224.375C1850.07 201.823 1842.97 185.344 1831.31 174.935C1819.65 164.18 1805.45 158.802 1788.69 158.802C1769.38 158.802 1753.72 164.527 1741.7 175.976C1729.67 187.425 1722.21 203.558 1719.29 224.375H1852.62ZM1526.96 174.935C1538.62 184.303 1545.9 197.313 1548.82 213.966L1620.94 210.323C1618.39 189.16 1610.93 170.772 1598.54 155.159C1586.15 139.547 1570.13 127.578 1550.45 119.251C1531.15 110.577 1509.84 106.241 1486.52 106.241C1457.74 106.241 1432.61 112.139 1411.11 123.935C1389.62 135.731 1372.86 152.557 1360.84 174.415C1348.82 196.272 1342.81 221.599 1342.81 250.395C1342.81 279.192 1348.82 304.518 1360.84 326.376C1372.86 348.233 1389.62 365.06 1411.11 376.856C1432.61 388.652 1457.74 394.55 1486.52 394.55C1510.56 394.55 1532.42 390.213 1552.09 381.54C1571.77 372.519 1587.79 359.856 1600.18 343.549C1612.57 327.243 1620.03 308.161 1622.58 286.304L1549.91 283.181C1547.36 301.569 1540.25 315.794 1528.6 325.855C1516.94 335.57 1502.91 340.427 1486.52 340.427C1463.94 340.427 1446.45 332.621 1434.06 317.008C1421.68 301.396 1415.49 279.192 1415.49 250.395C1415.49 221.599 1421.68 199.395 1434.06 183.782C1446.45 168.17 1463.94 160.364 1486.52 160.364C1502.19 160.364 1515.66 165.221 1526.96 174.935ZM1172.15 112.473H1237.24L1239.12 165.559C1243.74 150.533 1250.16 138.864 1258.39 130.552C1270.32 118.5 1286.96 112.473 1308.29 112.473H1334.87V169.293H1307.75C1292.56 169.293 1280.09 171.359 1270.32 175.491C1260.92 179.624 1253.69 186.166 1248.63 195.12C1243.93 204.073 1241.58 215.437 1241.58 229.211V388.306H1172.15V112.473ZM871.925 174.415C859.904 196.272 853.893 221.599 853.893 250.395C853.893 279.192 859.904 304.518 871.925 326.376C883.947 348.233 900.704 365.06 922.198 376.856C943.691 388.652 968.827 394.55 997.606 394.55C1028.93 394.55 1056.62 386.744 1080.66 371.131C1104.71 355.519 1121.1 334.702 1129.84 308.682L1058.26 303.478C1052.8 315.274 1044.6 324.641 1033.67 331.58C1022.74 338.519 1010.72 341.988 997.606 341.988C976.841 341.988 960.266 335.57 947.88 322.733C935.858 309.549 929.119 291.508 927.662 268.61H1133.67V252.477C1133.3 220.905 1127.11 194.191 1115.09 172.333C1103.07 150.476 1086.86 133.996 1066.46 122.894C1046.06 111.792 1023.11 106.241 997.606 106.241C968.827 106.241 943.691 112.139 922.198 123.935C900.704 135.731 883.947 152.557 871.925 174.415ZM1040.23 174.935C1051.88 185.344 1058.99 201.823 1061.54 224.375H928.208C931.123 203.558 938.591 187.425 950.612 175.976C962.634 164.527 978.298 158.802 997.606 158.802C1014.36 158.802 1028.57 164.18 1040.23 174.935Z" fill="white"/>
+</g>
+</svg>
--- a/openclaw/docs/auth-credential-semantics.md
+++ b/openclaw/docs/auth-credential-semantics.md
@ -0,0 +1,80 @@
+---
+title: "Auth Credential Semantics"
+summary: "Canonical credential eligibility and resolution semantics for auth profiles"
+read_when:
+  - Working on auth profile resolution or credential routing
+  - Debugging model auth failures or profile order
+---
+
+# Auth Credential Semantics
+
+This document defines the canonical credential eligibility and resolution semantics used across:
+
+- `resolveAuthProfileOrder`
+- `resolveApiKeyForProfile`
+- `models status --probe`
+- `doctor-auth`
+
+The goal is to keep selection-time and runtime behavior aligned.
+
+## Stable Probe Reason Codes
+
+- `ok`
+- `excluded_by_auth_order`
+- `missing_credential`
+- `invalid_expires`
+- `expired`
+- `unresolved_ref`
+- `no_model`
+
+## Token Credentials
+
+Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`.
+
+### Eligibility rules
+
+1. A token profile is ineligible when both `token` and `tokenRef` are absent.
+2. `expires` is optional.
+3. If `expires` is present, it must be a finite number greater than `0`.
+4. If `expires` is invalid (`NaN`, `0`, negative, non-finite, or wrong type), the profile is ineligible with `invalid_expires`.
+5. If `expires` is in the past, the profile is ineligible with `expired`.
+6. `tokenRef` does not bypass `expires` validation.
+
+### Resolution rules
+
+1. Resolver semantics match eligibility semantics for `expires`.
+2. For eligible profiles, token material may be resolved from inline value or `tokenRef`.
+3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output.
+
+## Explicit Auth Order Filtering
+
+- When `auth.order.<provider>` or the auth-store order override is set for a
+  provider, `models status --probe` only probes profile ids that remain in the
+  resolved auth order for that provider.
+- A stored profile for that provider that is omitted from the explicit order is
+  not silently tried later. Probe output reports it with
+  `reasonCode: excluded_by_auth_order` and the detail
+  `Excluded by auth.order for this provider.`
+
+## Probe Target Resolution
+
+- Probe targets can come from auth profiles, environment credentials, or
+  `models.json`.
+- If a provider has credentials but OpenClaw cannot resolve a probeable model
+  candidate for it, `models status --probe` reports `status: no_model` with
+  `reasonCode: no_model`.
+
+## OAuth SecretRef Policy Guard
+
+- SecretRef input is for static credentials only.
+- If a profile credential is `type: "oauth"`, SecretRef objects are not supported for that profile credential material.
+- If `auth.profiles.<id>.mode` is `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
+- Violations are hard failures in startup/reload auth resolution paths.
+
+## Legacy-Compatible Messaging
+
+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.
--- a/openclaw/docs/automation/auth-monitoring.md
+++ b/openclaw/docs/automation/auth-monitoring.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /gateway/authentication"
+title: "Auth Monitoring"
+---
+
+# Auth Monitoring
+
+This page moved to [Authentication](/gateway/authentication). See [Authentication](/gateway/authentication) for auth monitoring documentation.
--- a/openclaw/docs/automation/clawflow.md
+++ b/openclaw/docs/automation/clawflow.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to Task Flow"
+title: "ClawFlow"
+---
+
+# ClawFlow
+
+ClawFlow was renamed to [Task Flow](/automation/taskflow). See [Task Flow](/automation/taskflow) for the current documentation.
--- a/openclaw/docs/automation/cron-jobs.md
+++ b/openclaw/docs/automation/cron-jobs.md
@ -0,0 +1,424 @@
+---
+summary: "Scheduled jobs, webhooks, and Gmail PubSub triggers for the Gateway scheduler"
+read_when:
+  - Scheduling background jobs or wakeups
+  - Wiring external triggers (webhooks, Gmail) into OpenClaw
+  - Deciding between heartbeat and cron for scheduled tasks
+title: "Scheduled Tasks"
+---
+
+# Scheduled Tasks (Cron)
+
+Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output back to a chat channel or webhook endpoint.
+
+## Quick start
+
+```bash
+# Add a one-shot reminder
+openclaw cron add \
+  --name "Reminder" \
+  --at "2026-02-01T16:00:00Z" \
+  --session main \
+  --system-event "Reminder: check the cron docs draft" \
+  --wake now \
+  --delete-after-run
+
+# Check your jobs
+openclaw cron list
+
+# See run history
+openclaw cron runs --id <job-id>
+```
+
+## How cron works
+
+- Cron runs **inside the Gateway** process (not inside the model).
+- Jobs persist at `~/.openclaw/cron/jobs.json` so restarts do not lose schedules.
+- All cron executions create [background task](/automation/tasks) records.
+- One-shot jobs (`--at`) auto-delete after success by default.
+- Isolated cron runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session when the run completes, so detached browser automation does not leave orphaned processes behind.
+- Isolated cron runs also guard against stale acknowledgement replies. If the
+  first result is just an interim status update (`on it`, `pulling everything
+together`, and similar hints) and no descendant subagent run is still
+  responsible for the final answer, OpenClaw re-prompts once for the actual
+  result before delivery.
+
+<a id="maintenance"></a>
+
+Task reconciliation for cron is runtime-owned: an active cron task stays live while the
+cron runtime still tracks that job as running, even if an old child session row still exists.
+Once the runtime stops owning the job and the 5-minute grace window expires, maintenance can
+mark the task `lost`.
+
+## Schedule types
+
+| Kind    | CLI flag  | Description                                             |
+| ------- | --------- | ------------------------------------------------------- |
+| `at`    | `--at`    | One-shot timestamp (ISO 8601 or relative like `20m`)    |
+| `every` | `--every` | Fixed interval                                          |
+| `cron`  | `--cron`  | 5-field or 6-field cron expression with optional `--tz` |
+
+Timestamps without a timezone are treated as UTC. Add `--tz America/New_York` for local wall-clock scheduling.
+
+Recurring top-of-hour expressions are automatically staggered by up to 5 minutes to reduce load spikes. Use `--exact` to force precise timing or `--stagger 30s` for an explicit window.
+
+### Day-of-month and day-of-week use OR logic
+
+Cron expressions are parsed by [croner](https://github.com/Hexagon/croner). When both the day-of-month and day-of-week fields are non-wildcard, croner matches when **either** field matches — not both. This is standard Vixie cron behavior.
+
+```
+# Intended: "9 AM on the 15th, only if it's a Monday"
+# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
+0 9 15 * 1
+```
+
+This fires ~5–6 times per month instead of 0–1 times per month. OpenClaw uses Croner's default OR behavior here. To require both conditions, use Croner's `+` day-of-week modifier (`0 9 15 * +1`) or schedule on one field and guard the other in your job's prompt or command.
+
+## Execution styles
+
+| Style           | `--session` value   | Runs in                  | Best for                        |
+| --------------- | ------------------- | ------------------------ | ------------------------------- |
+| Main session    | `main`              | Next heartbeat turn      | Reminders, system events        |
+| Isolated        | `isolated`          | Dedicated `cron:<jobId>` | Reports, background chores      |
+| Current session | `current`           | Bound at creation time   | Context-aware recurring work    |
+| Custom session  | `session:custom-id` | Persistent named session | Workflows that build on history |
+
+**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
+
+For isolated jobs, runtime teardown now includes best-effort browser cleanup for that cron session. Cleanup failures are ignored so the actual cron result still wins.
+
+When isolated cron runs orchestrate subagents, delivery also prefers the final
+descendant output over stale parent interim text. If descendants are still
+running, OpenClaw suppresses that partial parent update instead of announcing it.
+
+### Payload options for isolated jobs
+
+- `--message`: prompt text (required for isolated)
+- `--model` / `--thinking`: model and thinking level overrides
+- `--light-context`: skip workspace bootstrap file injection
+- `--tools exec,read`: restrict which tools the job can use
+
+`--model` uses the selected allowed model for that job. If the requested model
+is not allowed, cron logs a warning and falls back to the job's agent/default
+model selection instead. Configured fallback chains still apply, but a plain
+model override with no explicit per-job fallback list no longer appends the
+agent primary as a hidden extra retry target.
+
+Model-selection precedence for isolated jobs is:
+
+1. Gmail hook model override (when the run came from Gmail and that override is allowed)
+2. Per-job payload `model`
+3. Stored cron session model override
+4. Agent/default model selection
+
+Fast mode follows the resolved live selection too. If the selected model config
+has `params.fastMode`, isolated cron uses that by default. A stored session
+`fastMode` override still wins over config in either direction.
+
+If an isolated run hits a live model-switch handoff, cron retries with the
+switched provider/model and persists that live selection before retrying. When
+the switch also carries a new auth profile, cron persists that auth profile
+override too. Retries are bounded: after the initial attempt plus 2 switch
+retries, cron aborts instead of looping forever.
+
+## Delivery and output
+
+| Mode       | What happens                                             |
+| ---------- | -------------------------------------------------------- |
+| `announce` | Deliver summary to target channel (default for isolated) |
+| `webhook`  | POST finished event payload to a URL                     |
+| `none`     | Internal only, no delivery                               |
+
+Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:<id>`, `user:<id>`).
+
+For cron-owned isolated jobs, the runner owns the final delivery path. The
+agent is prompted to return a plain-text summary, and that summary is then sent
+through `announce`, `webhook`, or kept internal for `none`. `--no-deliver`
+does not hand delivery back to the agent; it keeps the run internal.
+
+If the original task explicitly says to message some external recipient, the
+agent should note who/where that message should go in its output instead of
+trying to send it directly.
+
+Failure notifications follow a separate destination path:
+
+- `cron.failureDestination` sets a global default for failure notifications.
+- `job.delivery.failureDestination` overrides that per job.
+- If neither is set and the job already delivers via `announce`, failure notifications now fall back to that primary announce target.
+- `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`.
+
+## CLI examples
+
+One-shot reminder (main session):
+
+```bash
+openclaw cron add \
+  --name "Calendar check" \
+  --at "20m" \
+  --session main \
+  --system-event "Next heartbeat: check calendar." \
+  --wake now
+```
+
+Recurring isolated job with delivery:
+
+```bash
+openclaw cron add \
+  --name "Morning brief" \
+  --cron "0 7 * * *" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --announce \
+  --channel slack \
+  --to "channel:C1234567890"
+```
+
+Isolated job with model and thinking override:
+
+```bash
+openclaw cron add \
+  --name "Deep analysis" \
+  --cron "0 6 * * 1" \
+  --tz "America/Los_Angeles" \
+  --session isolated \
+  --message "Weekly deep analysis of project progress." \
+  --model "opus" \
+  --thinking high \
+  --announce
+```
+
+## Webhooks
+
+Gateway can expose HTTP webhook endpoints for external triggers. Enable in config:
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "shared-secret",
+    path: "/hooks",
+  },
+}
+```
+
+### Authentication
+
+Every request must include the hook token via header:
+
+- `Authorization: Bearer <token>` (recommended)
+- `x-openclaw-token: <token>`
+
+Query-string tokens are rejected.
+
+### POST /hooks/wake
+
+Enqueue a system event for the main session:
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/wake \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"New email received","mode":"now"}'
+```
+
+- `text` (required): event description
+- `mode` (optional): `now` (default) or `next-heartbeat`
+
+### POST /hooks/agent
+
+Run an isolated agent turn:
+
+```bash
+curl -X POST http://127.0.0.1:18789/hooks/agent \
+  -H 'Authorization: Bearer SECRET' \
+  -H 'Content-Type: application/json' \
+  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'
+```
+
+Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
+
+### Mapped hooks (POST /hooks/\<name\>)
+
+Custom hook names are resolved via `hooks.mappings` in config. Mappings can transform arbitrary payloads into `wake` or `agent` actions with templates or code transforms.
+
+### Security
+
+- Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
+- Use a dedicated hook token; do not reuse gateway auth tokens.
+- Keep `hooks.path` on a dedicated subpath; `/` is rejected.
+- Set `hooks.allowedAgentIds` to limit explicit `agentId` routing.
+- Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.
+- If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to constrain allowed session key shapes.
+- Hook payloads are wrapped with safety boundaries by default.
+
+## Gmail PubSub integration
+
+Wire Gmail inbox triggers to OpenClaw via Google PubSub.
+
+**Prerequisites**: `gcloud` CLI, `gog` (gogcli), OpenClaw hooks enabled, Tailscale for the public HTTPS endpoint.
+
+### Wizard setup (recommended)
+
+```bash
+openclaw webhooks gmail setup --account openclaw@gmail.com
+```
+
+This writes `hooks.gmail` config, enables the Gmail preset, and uses Tailscale Funnel for the push endpoint.
+
+### Gateway auto-start
+
+When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts `gog gmail watch serve` on boot and auto-renews the watch. Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` to opt out.
+
+### Manual one-time setup
+
+1. Select the GCP project that owns the OAuth client used by `gog`:
+
+```bash
+gcloud auth login
+gcloud config set project <project-id>
+gcloud services enable gmail.googleapis.com pubsub.googleapis.com
+```
+
+2. Create topic and grant Gmail push access:
+
+```bash
+gcloud pubsub topics create gog-gmail-watch
+gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
+  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
+  --role=roles/pubsub.publisher
+```
+
+3. Start the watch:
+
+```bash
+gog gmail watch start \
+  --account openclaw@gmail.com \
+  --label INBOX \
+  --topic projects/<project-id>/topics/gog-gmail-watch
+```
+
+### Gmail model override
+
+```json5
+{
+  hooks: {
+    gmail: {
+      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
+      thinking: "off",
+    },
+  },
+}
+```
+
+## Managing jobs
+
+```bash
+# List all jobs
+openclaw cron list
+
+# Edit a job
+openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
+
+# Force run a job now
+openclaw cron run <jobId>
+
+# Run only if due
+openclaw cron run <jobId> --due
+
+# View run history
+openclaw cron runs --id <jobId> --limit 50
+
+# Delete a job
+openclaw cron remove <jobId>
+
+# Agent selection (multi-agent setups)
+openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
+openclaw cron edit <jobId> --clear-agent
+```
+
+Model override note:
+
+- `openclaw cron add|edit --model ...` changes the job's selected model.
+- If the model is allowed, that exact provider/model reaches the isolated agent
+  run.
+- If it is not allowed, cron warns and falls back to the job's agent/default
+  model selection.
+- Configured fallback chains still apply, but a plain `--model` override with
+  no explicit per-job fallback list no longer falls through to the agent
+  primary as a silent extra retry target.
+
+## Configuration
+
+```json5
+{
+  cron: {
+    enabled: true,
+    store: "~/.openclaw/cron/jobs.json",
+    maxConcurrentRuns: 1,
+    retry: {
+      maxAttempts: 3,
+      backoffMs: [60000, 120000, 300000],
+      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
+    },
+    webhookToken: "replace-with-dedicated-webhook-token",
+    sessionRetention: "24h",
+    runLog: { maxBytes: "2mb", keepLines: 2000 },
+  },
+}
+```
+
+Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
+
+**One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
+
+**Recurring retry**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
+
+**Maintenance**: `cron.sessionRetention` (default `24h`) prunes isolated run-session entries. `cron.runLog.maxBytes` / `cron.runLog.keepLines` auto-prune run-log files.
+
+## Troubleshooting
+
+### Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw cron status
+openclaw cron list
+openclaw cron runs --id <jobId> --limit 20
+openclaw system heartbeat last
+openclaw logs --follow
+openclaw doctor
+```
+
+### Cron not firing
+
+- Check `cron.enabled` and `OPENCLAW_SKIP_CRON` env var.
+- Confirm the Gateway is running continuously.
+- For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
+- `reason: not-due` in run output means manual run was checked with `openclaw cron run <jobId> --due` and the job was not due yet.
+
+### Cron fired but no delivery
+
+- Delivery mode is `none` means no external message is expected.
+- Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
+- Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
+- If the isolated run returns only the silent token (`NO_REPLY` / `no_reply`),
+  OpenClaw suppresses direct outbound delivery and also suppresses the fallback
+  queued summary path, so nothing is posted back to chat.
+- For cron-owned isolated jobs, do not expect the agent to use the message tool
+  as a fallback. The runner owns final delivery; `--no-deliver` keeps it
+  internal instead of allowing a direct send.
+
+### Timezone gotchas
+
+- Cron without `--tz` uses the gateway host timezone.
+- `at` schedules without timezone are treated as UTC.
+- Heartbeat `activeHours` uses configured timezone resolution.
+
+## Related
+
+- [Automation & Tasks](/automation) — all automation mechanisms at a glance
+- [Background Tasks](/automation/tasks) — task ledger for cron executions
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Timezone](/concepts/timezone) — timezone configuration
--- a/openclaw/docs/automation/cron-vs-heartbeat.md
+++ b/openclaw/docs/automation/cron-vs-heartbeat.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /automation"
+title: "Cron vs Heartbeat"
+---
+
+# Cron vs Heartbeat
+
+This page moved to [Automation & Tasks](/automation). See [Automation & Tasks](/automation) for the decision guide comparing cron and heartbeat.
--- a/openclaw/docs/automation/gmail-pubsub.md
+++ b/openclaw/docs/automation/gmail-pubsub.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Gmail PubSub"
+---
+
+# Gmail PubSub
+
+This page moved to [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration). See [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration) for Gmail PubSub documentation.
--- a/openclaw/docs/automation/hooks.md
+++ b/openclaw/docs/automation/hooks.md
@ -0,0 +1,319 @@
+---
+summary: "Hooks: event-driven automation for commands and lifecycle events"
+read_when:
+  - You want event-driven automation for /new, /reset, /stop, and agent lifecycle events
+  - You want to build, install, or debug hooks
+title: "Hooks"
+---
+
+# Hooks
+
+Hooks are small scripts that run when something happens inside the Gateway. They are automatically discovered from directories and can be inspected with `openclaw hooks`.
+
+There are two kinds of hooks in OpenClaw:
+
+- **Internal hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
+- **Webhooks**: external HTTP endpoints that let other systems trigger work in OpenClaw. See [Webhooks](/automation/cron-jobs#webhooks).
+
+Hooks can also be bundled inside plugins. `openclaw hooks list` shows both standalone hooks and plugin-managed hooks.
+
+## Quick start
+
+```bash
+# List available hooks
+openclaw hooks list
+
+# Enable a hook
+openclaw hooks enable session-memory
+
+# Check hook status
+openclaw hooks check
+
+# Get detailed information
+openclaw hooks info session-memory
+```
+
+## Event types
+
+| Event                    | When it fires                                    |
+| ------------------------ | ------------------------------------------------ |
+| `command:new`            | `/new` command issued                            |
+| `command:reset`          | `/reset` command issued                          |
+| `command:stop`           | `/stop` command issued                           |
+| `command`                | Any command event (general listener)             |
+| `session:compact:before` | Before compaction summarizes history             |
+| `session:compact:after`  | After compaction completes                       |
+| `session:patch`          | When session properties are modified             |
+| `agent:bootstrap`        | Before workspace bootstrap files are injected    |
+| `gateway:startup`        | After channels start and hooks are loaded        |
+| `message:received`       | Inbound message from any channel                 |
+| `message:transcribed`    | After audio transcription completes              |
+| `message:preprocessed`   | After all media and link understanding completes |
+| `message:sent`           | Outbound message delivered                       |
+
+## Writing hooks
+
+### Hook structure
+
+Each hook is a directory containing two files:
+
+```
+my-hook/
+├── HOOK.md          # Metadata + documentation
+└── handler.ts       # Handler implementation
+```
+
+### HOOK.md format
+
+```markdown
+---
+name: my-hook
+description: "Short description of what this hook does"
+metadata:
+  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
+---
+
+# My Hook
+
+Detailed documentation goes here.
+```
+
+**Metadata fields** (`metadata.openclaw`):
+
+| Field      | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `emoji`    | Display emoji for CLI                                |
+| `events`   | Array of events to listen for                        |
+| `export`   | Named export to use (defaults to `"default"`)        |
+| `os`       | Required platforms (e.g., `["darwin", "linux"]`)     |
+| `requires` | Required `bins`, `anyBins`, `env`, or `config` paths |
+| `always`   | Bypass eligibility checks (boolean)                  |
+| `install`  | Installation methods                                 |
+
+### Handler implementation
+
+```typescript
+const handler = async (event) => {
+  if (event.type !== "command" || event.action !== "new") {
+    return;
+  }
+
+  console.log(`[my-hook] New command triggered`);
+  // Your logic here
+
+  // Optionally send message to user
+  event.messages.push("Hook executed!");
+};
+
+export default handler;
+```
+
+Each event includes: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push to send to user), and `context` (event-specific data).
+
+### Event context highlights
+
+**Command events** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
+
+**Message events** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (provider-specific data including `senderId`, `senderName`, `guildId`).
+
+**Message events** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`.
+
+**Message events** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
+
+**Message events** (`message:preprocessed`): `context.bodyForAgent` (final enriched body), `context.from`, `context.channelId`.
+
+**Bootstrap events** (`agent:bootstrap`): `context.bootstrapFiles` (mutable array), `context.agentId`.
+
+**Session patch events** (`session:patch`): `context.sessionEntry`, `context.patch` (only changed fields), `context.cfg`. Only privileged clients can trigger patch events.
+
+**Compaction events**: `session:compact:before` includes `messageCount`, `tokenCount`. `session:compact:after` adds `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
+
+## Hook discovery
+
+Hooks are discovered from these directories, in order of increasing override precedence:
+
+1. **Bundled hooks**: shipped with OpenClaw
+2. **Plugin hooks**: hooks bundled inside installed plugins
+3. **Managed hooks**: `~/.openclaw/hooks/` (user-installed, shared across workspaces). Extra directories from `hooks.internal.load.extraDirs` share this precedence.
+4. **Workspace hooks**: `<workspace>/hooks/` (per-agent, disabled by default until explicitly enabled)
+
+Workspace hooks can add new hook names but cannot override bundled, managed, or plugin-provided hooks with the same name.
+
+### Hook packs
+
+Hook packs are npm packages that export hooks via `openclaw.hooks` in `package.json`. Install with:
+
+```bash
+openclaw plugins install <path-or-spec>
+```
+
+Npm specs are registry-only (package name + optional exact version or dist-tag). Git/URL/file specs and semver ranges are rejected.
+
+## Bundled hooks
+
+| Hook                  | Events                         | What it does                                          |
+| --------------------- | ------------------------------ | ----------------------------------------------------- |
+| session-memory        | `command:new`, `command:reset` | Saves session context to `<workspace>/memory/`        |
+| bootstrap-extra-files | `agent:bootstrap`              | Injects additional bootstrap files from glob patterns |
+| command-logger        | `command`                      | Logs all commands to `~/.openclaw/logs/commands.log`  |
+| boot-md               | `gateway:startup`              | Runs `BOOT.md` when the gateway starts                |
+
+Enable any bundled hook:
+
+```bash
+openclaw hooks enable <hook-name>
+```
+
+<a id="session-memory"></a>
+
+### session-memory details
+
+Extracts the last 15 user/assistant messages, generates a descriptive filename slug via LLM, and saves to `<workspace>/memory/YYYY-MM-DD-slug.md`. Requires `workspace.dir` to be configured.
+
+<a id="bootstrap-extra-files"></a>
+
+### bootstrap-extra-files config
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "bootstrap-extra-files": {
+          "enabled": true,
+          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
+        }
+      }
+    }
+  }
+}
+```
+
+Paths resolve relative to workspace. Only recognized bootstrap basenames are loaded (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
+
+<a id="command-logger"></a>
+
+### command-logger details
+
+Logs every slash command to `~/.openclaw/logs/commands.log`.
+
+<a id="boot-md"></a>
+
+### boot-md details
+
+Runs `BOOT.md` from the active workspace when the gateway starts.
+
+## Plugin hooks
+
+Plugins can register hooks through the Plugin SDK for deeper integration: intercepting tool calls, modifying prompts, controlling message flow, and more. The Plugin SDK exposes 28 hooks covering model resolution, agent lifecycle, message flow, tool execution, subagent coordination, and gateway lifecycle.
+
+For the complete plugin hook reference including `before_tool_call`, `before_agent_reply`, `before_install`, and all other plugin hooks, see [Plugin Architecture](/plugins/architecture#provider-runtime-hooks).
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "session-memory": { "enabled": true },
+        "command-logger": { "enabled": false }
+      }
+    }
+  }
+}
+```
+
+Per-hook environment variables:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "my-hook": {
+          "enabled": true,
+          "env": { "MY_CUSTOM_VAR": "value" }
+        }
+      }
+    }
+  }
+}
+```
+
+Extra hook directories:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "load": {
+        "extraDirs": ["/path/to/more/hooks"]
+      }
+    }
+  }
+}
+```
+
+<Note>
+The legacy `hooks.internal.handlers` array config format is still supported for backwards compatibility, but new hooks should use the discovery-based system.
+</Note>
+
+## CLI reference
+
+```bash
+# List all hooks (add --eligible, --verbose, or --json)
+openclaw hooks list
+
+# Show detailed info about a hook
+openclaw hooks info <hook-name>
+
+# Show eligibility summary
+openclaw hooks check
+
+# Enable/disable
+openclaw hooks enable <hook-name>
+openclaw hooks disable <hook-name>
+```
+
+## Best practices
+
+- **Keep handlers fast.** Hooks run during command processing. Fire-and-forget heavy work with `void processInBackground(event)`.
+- **Handle errors gracefully.** Wrap risky operations in try/catch; do not throw so other handlers can run.
+- **Filter events early.** Return immediately if the event type/action is not relevant.
+- **Use specific event keys.** Prefer `"events": ["command:new"]` over `"events": ["command"]` to reduce overhead.
+
+## Troubleshooting
+
+### Hook not discovered
+
+```bash
+# Verify directory structure
+ls -la ~/.openclaw/hooks/my-hook/
+# Should show: HOOK.md, handler.ts
+
+# List all discovered hooks
+openclaw hooks list
+```
+
+### Hook not eligible
+
+```bash
+openclaw hooks info my-hook
+```
+
+Check for missing binaries (PATH), environment variables, config values, or OS compatibility.
+
+### Hook not executing
+
+1. Verify the hook is enabled: `openclaw hooks list`
+2. Restart your gateway process so hooks reload.
+3. Check gateway logs: `./scripts/clawlog.sh | grep hook`
+
+## Related
+
+- [CLI Reference: hooks](/cli/hooks)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — full plugin hook reference
+- [Configuration](/gateway/configuration-reference#hooks)
--- a/openclaw/docs/automation/index.md
+++ b/openclaw/docs/automation/index.md
@ -0,0 +1,115 @@
+---
+summary: "Overview of automation mechanisms: tasks, cron, hooks, standing orders, and Task Flow"
+read_when:
+  - Deciding how to automate work with OpenClaw
+  - Choosing between heartbeat, cron, hooks, and standing orders
+  - Looking for the right automation entry point
+title: "Automation & Tasks"
+---
+
+# Automation & Tasks
+
+OpenClaw runs work in the background through tasks, scheduled jobs, event hooks, and standing instructions. This page helps you choose the right mechanism and understand how they fit together.
+
+## Quick decision guide
+
+```mermaid
+flowchart TD
+    START([What do you need?]) --> Q1{Schedule work?}
+    START --> Q2{Track detached work?}
+    START --> Q3{Orchestrate multi-step flows?}
+    START --> Q4{React to lifecycle events?}
+    START --> Q5{Give the agent persistent instructions?}
+
+    Q1 -->|Yes| Q1a{Exact timing or flexible?}
+    Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
+    Q1a -->|Flexible| HEARTBEAT[Heartbeat]
+
+    Q2 -->|Yes| TASKS[Background Tasks]
+    Q3 -->|Yes| FLOW[Task Flow]
+    Q4 -->|Yes| HOOKS[Hooks]
+    Q5 -->|Yes| SO[Standing Orders]
+```
+
+| Use case                                | Recommended            | Why                                              |
+| --------------------------------------- | ---------------------- | ------------------------------------------------ |
+| Send daily report at 9 AM sharp         | Scheduled Tasks (Cron) | Exact timing, isolated execution                 |
+| Remind me in 20 minutes                 | Scheduled Tasks (Cron) | One-shot with precise timing (`--at`)            |
+| Run weekly deep analysis                | Scheduled Tasks (Cron) | Standalone task, can use different model         |
+| Check inbox every 30 min                | Heartbeat              | Batches with other checks, context-aware         |
+| Monitor calendar for upcoming events    | Heartbeat              | Natural fit for periodic awareness               |
+| Inspect status of a subagent or ACP run | Background Tasks       | Tasks ledger tracks all detached work            |
+| Audit what ran and when                 | Background Tasks       | `openclaw tasks list` and `openclaw tasks audit` |
+| Multi-step research then summarize      | Task Flow              | Durable orchestration with revision tracking     |
+| Run a script on session reset           | Hooks                  | Event-driven, fires on lifecycle events          |
+| Execute code on every tool call         | Hooks                  | Hooks can filter by event type                   |
+| Always check compliance before replying | Standing Orders        | Injected into every session automatically        |
+
+### Scheduled Tasks (Cron) vs Heartbeat
+
+| Dimension       | Scheduled Tasks (Cron)              | Heartbeat                             |
+| --------------- | ----------------------------------- | ------------------------------------- |
+| Timing          | Exact (cron expressions, one-shot)  | Approximate (default every 30 min)    |
+| Session context | Fresh (isolated) or shared          | Full main-session context             |
+| Task records    | Always created                      | Never created                         |
+| Delivery        | Channel, webhook, or silent         | Inline in main session                |
+| Best for        | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
+
+Use Scheduled Tasks (Cron) when you need precise timing or isolated execution. Use Heartbeat when the work benefits from full session context and approximate timing is fine.
+
+## Core concepts
+
+### Scheduled tasks (cron)
+
+Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
+
+See [Scheduled Tasks](/automation/cron-jobs).
+
+### Tasks
+
+The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use `openclaw tasks list` and `openclaw tasks audit` to inspect them.
+
+See [Background Tasks](/automation/tasks).
+
+### Task Flow
+
+Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and `openclaw tasks flow list|show|cancel` for inspection.
+
+See [Task Flow](/automation/taskflow).
+
+### Standing orders
+
+Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with cron for time-based enforcement.
+
+See [Standing Orders](/automation/standing-orders).
+
+### Hooks
+
+Hooks are event-driven scripts triggered by agent lifecycle events (`/new`, `/reset`, `/stop`), session compaction, gateway startup, message flow, and tool calls. Hooks are automatically discovered from directories and can be managed with `openclaw hooks`.
+
+See [Hooks](/automation/hooks).
+
+### Heartbeat
+
+Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` for a small checklist, or a `tasks:` block when you want due-only periodic checks inside heartbeat itself. Empty heartbeat files skip as `empty-heartbeat-file`; due-only task mode skips as `no-tasks-due`.
+
+See [Heartbeat](/gateway/heartbeat).
+
+## How they work together
+
+- **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
+- **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
+- **Hooks** react to specific events (tool calls, session resets, compaction) with custom scripts.
+- **Standing orders** give the agent persistent context and authority boundaries.
+- **Task Flow** coordinates multi-step flows above individual tasks.
+- **Tasks** automatically track all detached work so you can inspect and audit it.
+
+## Related
+
+- [Scheduled Tasks](/automation/cron-jobs) — precise scheduling and one-shot reminders
+- [Background Tasks](/automation/tasks) — task ledger for all detached work
+- [Task Flow](/automation/taskflow) — durable multi-step flow orchestration
+- [Hooks](/automation/hooks) — event-driven lifecycle scripts
+- [Standing Orders](/automation/standing-orders) — persistent agent instructions
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [Configuration Reference](/gateway/configuration-reference) — all config keys
--- a/openclaw/docs/automation/poll.md
+++ b/openclaw/docs/automation/poll.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /tools/message"
+title: "Polls"
+---
+
+# Polls
+
+This page moved to [Message tool](/cli/message). See [Message tool](/cli/message) for poll documentation.
--- a/openclaw/docs/automation/standing-orders.md
+++ b/openclaw/docs/automation/standing-orders.md
@ -0,0 +1,254 @@
+---
+summary: "Define permanent operating authority for autonomous agent programs"
+read_when:
+  - Setting up autonomous agent workflows that run without per-task prompting
+  - Defining what the agent can do independently vs. what needs human approval
+  - Structuring multi-program agents with clear boundaries and escalation rules
+title: "Standing Orders"
+---
+
+# Standing Orders
+
+Standing orders grant your agent **permanent operating authority** for defined programs. Instead of giving individual task instructions each time, you define programs with clear scope, triggers, and escalation rules — and the agent executes autonomously within those boundaries.
+
+This is the difference between telling your assistant "send the weekly report" every Friday vs. granting standing authority: "You own the weekly report. Compile it every Friday, send it, and only escalate if something looks wrong."
+
+## Why Standing Orders?
+
+**Without standing orders:**
+
+- You must prompt the agent for every task
+- The agent sits idle between requests
+- Routine work gets forgotten or delayed
+- You become the bottleneck
+
+**With standing orders:**
+
+- The agent executes autonomously within defined boundaries
+- Routine work happens on schedule without prompting
+- You only get involved for exceptions and approvals
+- The agent fills idle time productively
+
+## How They Work
+
+Standing orders are defined in your [agent workspace](/concepts/agent-workspace) files. The recommended approach is to include them directly in `AGENTS.md` (which is auto-injected every session) so the agent always has them in context. For larger configurations, you can also place them in a dedicated file like `standing-orders.md` and reference it from `AGENTS.md`.
+
+Each program specifies:
+
+1. **Scope** — what the agent is authorized to do
+2. **Triggers** — when to execute (schedule, event, or condition)
+3. **Approval gates** — what requires human sign-off before acting
+4. **Escalation rules** — when to stop and ask for help
+
+The agent loads these instructions every session via the workspace bootstrap files (see [Agent Workspace](/concepts/agent-workspace) for the full list of auto-injected files) and executes against them, combined with [cron jobs](/automation/cron-jobs) for time-based enforcement.
+
+<Tip>
+Put standing orders in `AGENTS.md` to guarantee they're loaded every session. The workspace bootstrap automatically injects `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` — but not arbitrary files in subdirectories.
+</Tip>
+
+## Anatomy of a Standing Order
+
+```markdown
+## Program: Weekly Status Report
+
+**Authority:** Compile data, generate report, deliver to stakeholders
+**Trigger:** Every Friday at 4 PM (enforced via cron job)
+**Approval gate:** None for standard reports. Flag anomalies for human review.
+**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
+
+### Execution Steps
+
+1. Pull metrics from configured sources
+2. Compare to prior week and targets
+3. Generate report in Reports/weekly/YYYY-MM-DD.md
+4. Deliver summary via configured channel
+5. Log completion to Agent/Logs/
+
+### What NOT to Do
+
+- Do not send reports to external parties
+- Do not modify source data
+- Do not skip delivery if metrics look bad — report accurately
+```
+
+## Standing Orders + Cron Jobs
+
+Standing orders define **what** the agent is authorized to do. [Cron jobs](/automation/cron-jobs) define **when** it happens. They work together:
+
+```
+Standing Order: "You own the daily inbox triage"
+    ↓
+Cron Job (8 AM daily): "Execute inbox triage per standing orders"
+    ↓
+Agent: Reads standing orders → executes steps → reports results
+```
+
+The cron job prompt should reference the standing order rather than duplicating it:
+
+```bash
+openclaw cron add \
+  --name daily-inbox-triage \
+  --cron "0 8 * * 1-5" \
+  --tz America/New_York \
+  --timeout-seconds 300 \
+  --announce \
+  --channel bluebubbles \
+  --to "+1XXXXXXXXXX" \
+  --message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."
+```
+
+## Examples
+
+### Example 1: Content & Social Media (Weekly Cycle)
+
+```markdown
+## Program: Content & Social Media
+
+**Authority:** Draft content, schedule posts, compile engagement reports
+**Approval gate:** All posts require owner review for first 30 days, then standing approval
+**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief)
+
+### Weekly Cycle
+
+- **Monday:** Review platform metrics and audience engagement
+- **Tuesday–Thursday:** Draft social posts, create blog content
+- **Friday:** Compile weekly marketing brief → deliver to owner
+
+### Content Rules
+
+- Voice must match the brand (see SOUL.md or brand voice guide)
+- Never identify as AI in public-facing content
+- Include metrics when available
+- Focus on value to audience, not self-promotion
+```
+
+### Example 2: Finance Operations (Event-Triggered)
+
+```markdown
+## Program: Financial Processing
+
+**Authority:** Process transaction data, generate reports, send summaries
+**Approval gate:** None for analysis. Recommendations require owner approval.
+**Trigger:** New data file detected OR scheduled monthly cycle
+
+### When New Data Arrives
+
+1. Detect new file in designated input directory
+2. Parse and categorize all transactions
+3. Compare against budget targets
+4. Flag: unusual items, threshold breaches, new recurring charges
+5. Generate report in designated output directory
+6. Deliver summary to owner via configured channel
+
+### Escalation Rules
+
+- Single item > $500: immediate alert
+- Category > budget by 20%: flag in report
+- Unrecognizable transaction: ask owner for categorization
+- Failed processing after 2 retries: report failure, do not guess
+```
+
+### Example 3: Monitoring & Alerts (Continuous)
+
+```markdown
+## Program: System Monitoring
+
+**Authority:** Check system health, restart services, send alerts
+**Approval gate:** Restart services automatically. Escalate if restart fails twice.
+**Trigger:** Every heartbeat cycle
+
+### Checks
+
+- Service health endpoints responding
+- Disk space above threshold
+- Pending tasks not stale (>24 hours)
+- Delivery channels operational
+
+### Response Matrix
+
+| Condition        | Action                   | Escalate?                |
+| ---------------- | ------------------------ | ------------------------ |
+| Service down     | Restart automatically    | Only if restart fails 2x |
+| Disk space < 10% | Alert owner              | Yes                      |
+| Stale task > 24h | Remind owner             | No                       |
+| Channel offline  | Log and retry next cycle | If offline > 2 hours     |
+```
+
+## The Execute-Verify-Report Pattern
+
+Standing orders work best when combined with strict execution discipline. Every task in a standing order should follow this loop:
+
+1. **Execute** — Do the actual work (don't just acknowledge the instruction)
+2. **Verify** — Confirm the result is correct (file exists, message delivered, data parsed)
+3. **Report** — Tell the owner what was done and what was verified
+
+```markdown
+### Execution Rules
+
+- Every task follows Execute-Verify-Report. No exceptions.
+- "I'll do that" is not execution. Do it, then report.
+- "Done" without verification is not acceptable. Prove it.
+- If execution fails: retry once with adjusted approach.
+- If still fails: report failure with diagnosis. Never silently fail.
+- Never retry indefinitely — 3 attempts max, then escalate.
+```
+
+This pattern prevents the most common agent failure mode: acknowledging a task without completing it.
+
+## Multi-Program Architecture
+
+For agents managing multiple concerns, organize standing orders as separate programs with clear boundaries:
+
+```markdown
+# Standing Orders
+
+## Program 1: [Domain A] (Weekly)
+
+...
+
+## Program 2: [Domain B] (Monthly + On-Demand)
+
+...
+
+## Program 3: [Domain C] (As-Needed)
+
+...
+
+## Escalation Rules (All Programs)
+
+- [Common escalation criteria]
+- [Approval gates that apply across programs]
+```
+
+Each program should have:
+
+- Its own **trigger cadence** (weekly, monthly, event-driven, continuous)
+- Its own **approval gates** (some programs need more oversight than others)
+- Clear **boundaries** (the agent should know where one program ends and another begins)
+
+## Best Practices
+
+### Do
+
+- Start with narrow authority and expand as trust builds
+- Define explicit approval gates for high-risk actions
+- Include "What NOT to do" sections — boundaries matter as much as permissions
+- Combine with cron jobs for reliable time-based execution
+- Review agent logs weekly to verify standing orders are being followed
+- Update standing orders as your needs evolve — they're living documents
+
+### Avoid
+
+- Grant broad authority on day one ("do whatever you think is best")
+- Skip escalation rules — every program needs a "when to stop and ask" clause
+- Assume the agent will remember verbal instructions — put everything in the file
+- Mix concerns in a single program — separate programs for separate domains
+- Forget to enforce with cron jobs — standing orders without triggers become suggestions
+
+## Related
+
+- [Automation & Tasks](/automation) — all automation mechanisms at a glance
+- [Cron Jobs](/automation/cron-jobs) — schedule enforcement for standing orders
+- [Hooks](/automation/hooks) — event-driven scripts for agent lifecycle events
+- [Webhooks](/automation/cron-jobs#webhooks) — inbound HTTP event triggers
+- [Agent Workspace](/concepts/agent-workspace) — where standing orders live, including the full list of auto-injected bootstrap files (AGENTS.md, SOUL.md, etc.)
--- a/openclaw/docs/automation/taskflow.md
+++ b/openclaw/docs/automation/taskflow.md
@ -0,0 +1,82 @@
+---
+summary: "Task Flow flow orchestration layer above background tasks"
+read_when:
+  - You want to understand how Task Flow relates to background tasks
+  - You encounter Task Flow or openclaw tasks flow in release notes or docs
+  - You want to inspect or manage durable flow state
+title: "Task Flow"
+---
+
+# Task Flow
+
+Task Flow is the flow orchestration substrate that sits above [background tasks](/automation/tasks). It manages durable multi-step flows with their own state, revision tracking, and sync semantics while individual tasks remain the unit of detached work.
+
+## When to use Task Flow
+
+Use Task Flow when work spans multiple sequential or branching steps and you need durable progress tracking across gateway restarts. For single background operations, a plain [task](/automation/tasks) is sufficient.
+
+| Scenario                              | Use                  |
+| ------------------------------------- | -------------------- |
+| Single background job                 | Plain task           |
+| Multi-step pipeline (A then B then C) | Task Flow (managed)  |
+| Observe externally created tasks      | Task Flow (mirrored) |
+| One-shot reminder                     | Cron job             |
+
+## Sync modes
+
+### Managed mode
+
+Task Flow owns the lifecycle end-to-end. It creates tasks as flow steps, drives them to completion, and advances the flow state automatically.
+
+Example: a weekly report flow that (1) gathers data, (2) generates the report, and (3) delivers it. Task Flow creates each step as a background task, waits for completion, then moves to the next step.
+
+```
+Flow: weekly-report
+  Step 1: gather-data     → task created → succeeded
+  Step 2: generate-report → task created → succeeded
+  Step 3: deliver         → task created → running
+```
+
+### Mirrored mode
+
+Task Flow observes externally created tasks and keeps flow state in sync without taking ownership of task creation. This is useful when tasks originate from cron jobs, CLI commands, or other sources and you want a unified view of their progress as a flow.
+
+Example: three independent cron jobs that together form a "morning ops" routine. A mirrored flow tracks their collective progress without controlling when or how they run.
+
+## Durable state and revision tracking
+
+Each flow persists its own state and tracks revisions so progress survives gateway restarts. Revision tracking enables conflict detection when multiple sources attempt to advance the same flow concurrently.
+
+## Cancel behavior
+
+`openclaw tasks flow cancel` sets a sticky cancel intent on the flow. Active tasks within the flow are cancelled, and no new steps are started. The cancel intent persists across restarts, so a cancelled flow stays cancelled even if the gateway restarts before all child tasks have terminated.
+
+## CLI commands
+
+```bash
+# List active and recent flows
+openclaw tasks flow list
+
+# Show details for a specific flow
+openclaw tasks flow show <lookup>
+
+# Cancel a running flow and its active tasks
+openclaw tasks flow cancel <lookup>
+```
+
+| Command                           | Description                                   |
+| --------------------------------- | --------------------------------------------- |
+| `openclaw tasks flow list`        | Shows tracked flows with status and sync mode |
+| `openclaw tasks flow show <id>`   | Inspect one flow by flow id or lookup key     |
+| `openclaw tasks flow cancel <id>` | Cancel a running flow and its active tasks    |
+
+## How flows relate to tasks
+
+Flows coordinate tasks, not replace them. A single flow may drive multiple background tasks over its lifetime. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
+
+## Related
+
+- [Background Tasks](/automation/tasks) — the detached work ledger that flows coordinate
+- [CLI: tasks](/cli/index#tasks) — CLI command reference for `openclaw tasks flow`
+- [Automation Overview](/automation) — all automation mechanisms at a glance
+- [Cron Jobs](/automation/cron-jobs) — scheduled jobs that may feed into flows
--- a/openclaw/docs/automation/tasks.md
+++ b/openclaw/docs/automation/tasks.md
@ -0,0 +1,328 @@
+---
+summary: "Background task tracking for ACP runs, subagents, isolated cron jobs, and CLI operations"
+read_when:
+  - Inspecting background work in progress or recently completed
+  - Debugging delivery failures for detached agent runs
+  - Understanding how background runs relate to sessions, cron, and heartbeat
+title: "Background Tasks"
+---
+
+# Background Tasks
+
+> **Looking for scheduling?** See [Automation & Tasks](/automation) for choosing the right mechanism. This page covers **tracking** background work, not scheduling it.
+
+Background tasks track work that runs **outside your main conversation session**:
+ACP runs, subagent spawns, isolated cron job executions, and CLI-initiated operations.
+
+Tasks do **not** replace sessions, cron jobs, or heartbeats — they are the **activity ledger** that records what detached work happened, when, and whether it succeeded.
+
+<Note>
+Not every agent run creates a task. Heartbeat turns and normal interactive chat do not. All cron executions, ACP spawns, subagent spawns, and CLI agent commands do.
+</Note>
+
+## TL;DR
+
+- Tasks are **records**, not schedulers — cron and heartbeat decide _when_ work runs, tasks track _what happened_.
+- ACP, subagents, all cron jobs, and CLI operations create tasks. Heartbeat turns do not.
+- Each task moves through `queued → running → terminal` (succeeded, failed, timed_out, cancelled, or lost).
+- Cron tasks stay live while the cron runtime still owns the job; chat-backed CLI tasks stay live only while their owning run context is still active.
+- Completion is push-driven: detached work can notify directly or wake the
+  requester session/heartbeat when it finishes, so status polling loops are
+  usually the wrong shape.
+- Isolated cron runs and subagent completions best-effort clean up tracked browser tabs/processes for their child session before final cleanup bookkeeping.
+- Isolated cron delivery suppresses stale interim parent replies while
+  descendant subagent work is still draining, and it prefers final descendant
+  output when that arrives before delivery.
+- Completion notifications are delivered directly to a channel or queued for the next heartbeat.
+- `openclaw tasks list` shows all tasks; `openclaw tasks audit` surfaces issues.
+- Terminal records are kept for 7 days, then automatically pruned.
+
+## Quick start
+
+```bash
+# List all tasks (newest first)
+openclaw tasks list
+
+# Filter by runtime or status
+openclaw tasks list --runtime acp
+openclaw tasks list --status running
+
+# Show details for a specific task (by ID, run ID, or session key)
+openclaw tasks show <lookup>
+
+# Cancel a running task (kills the child session)
+openclaw tasks cancel <lookup>
+
+# Change notification policy for a task
+openclaw tasks notify <lookup> state_changes
+
+# Run a health audit
+openclaw tasks audit
+
+# Preview or apply maintenance
+openclaw tasks maintenance
+openclaw tasks maintenance --apply
+
+# Inspect TaskFlow state
+openclaw tasks flow list
+openclaw tasks flow show <lookup>
+openclaw tasks flow cancel <lookup>
+```
+
+## What creates a task
+
+| Source                 | Runtime type | When a task record is created                          | Default notify policy |
+| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
+| ACP background runs    | `acp`        | Spawning a child ACP session                           | `done_only`           |
+| Subagent orchestration | `subagent`   | Spawning a subagent via `sessions_spawn`               | `done_only`           |
+| Cron jobs (all types)  | `cron`       | Every cron execution (main-session and isolated)       | `silent`              |
+| CLI operations         | `cli`        | `openclaw agent` commands that run through the gateway | `silent`              |
+| Agent media jobs       | `cli`        | Session-backed `video_generate` runs                   | `silent`              |
+
+Main-session cron tasks use `silent` notify policy by default — they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
+
+Session-backed `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished video itself. If you opt into `tools.media.asyncCompletion.directSend`, async `music_generate` and `video_generate` completions try direct channel delivery first before falling back to the requester-session wake path.
+
+While a session-backed `video_generate` task is still active, the tool also acts as a guardrail: repeated `video_generate` calls in that same session return the active task status instead of starting a second concurrent generation. Use `action: "status"` when you want an explicit progress/status lookup from the agent side.
+
+**What does not create tasks:**
+
+- Heartbeat turns — main-session; see [Heartbeat](/gateway/heartbeat)
+- Normal interactive chat turns
+- Direct `/command` responses
+
+## Task lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> queued
+    queued --> running : agent starts
+    running --> succeeded : completes ok
+    running --> failed : error
+    running --> timed_out : timeout exceeded
+    running --> cancelled : operator cancels
+    queued --> lost : session gone > 5 min
+    running --> lost : session gone > 5 min
+```
+
+| Status      | What it means                                                              |
+| ----------- | -------------------------------------------------------------------------- |
+| `queued`    | Created, waiting for the agent to start                                    |
+| `running`   | Agent turn is actively executing                                           |
+| `succeeded` | Completed successfully                                                     |
+| `failed`    | Completed with an error                                                    |
+| `timed_out` | Exceeded the configured timeout                                            |
+| `cancelled` | Stopped by the operator via `openclaw tasks cancel`                        |
+| `lost`      | The runtime lost authoritative backing state after a 5-minute grace period |
+
+Transitions happen automatically — when the associated agent run ends, the task status updates to match.
+
+`lost` is runtime-aware:
+
+- ACP tasks: backing ACP child session metadata disappeared.
+- Subagent tasks: backing child session disappeared from the target agent store.
+- Cron tasks: the cron runtime no longer tracks the job as active.
+- CLI tasks: isolated child-session tasks use the child session; chat-backed CLI tasks use the live run context instead, so lingering channel/group/direct session rows do not keep them alive.
+
+## Delivery and notifications
+
+When a task reaches a terminal state, OpenClaw notifies you. There are two delivery paths:
+
+**Direct delivery** — if the task has a channel target (the `requesterOrigin`), the completion message goes straight to that channel (Telegram, Discord, Slack, etc.). For subagent completions, OpenClaw also preserves bound thread/topic routing when available and can fill a missing `to` / account from the requester session's stored route (`lastChannel` / `lastTo` / `lastAccountId`) before giving up on direct delivery.
+
+**Session-queued delivery** — if direct delivery fails or no origin is set, the update is queued as a system event in the requester's session and surfaces on the next heartbeat.
+
+<Tip>
+Task completion triggers an immediate heartbeat wake so you see the result quickly — you do not have to wait for the next scheduled heartbeat tick.
+</Tip>
+
+That means the usual workflow is push-based: start detached work once, then let
+the runtime wake or notify you on completion. Poll task state only when you
+need debugging, intervention, or an explicit audit.
+
+### Notification policies
+
+Control how much you hear about each task:
+
+| Policy                | What is delivered                                                       |
+| --------------------- | ----------------------------------------------------------------------- |
+| `done_only` (default) | Only terminal state (succeeded, failed, etc.) — **this is the default** |
+| `state_changes`       | Every state transition and progress update                              |
+| `silent`              | Nothing at all                                                          |
+
+Change the policy while a task is running:
+
+```bash
+openclaw tasks notify <lookup> state_changes
+```
+
+## CLI reference
+
+### `tasks list`
+
+```bash
+openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
+```
+
+Output columns: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
+
+### `tasks show`
+
+```bash
+openclaw tasks show <lookup>
+```
+
+The lookup token accepts a task ID, run ID, or session key. Shows the full record including timing, delivery state, error, and terminal summary.
+
+### `tasks cancel`
+
+```bash
+openclaw tasks cancel <lookup>
+```
+
+For ACP and subagent tasks, this kills the child session. For CLI-tracked tasks, cancellation is recorded in the task registry (there is no separate child runtime handle). Status transitions to `cancelled` and a delivery notification is sent when applicable.
+
+### `tasks notify`
+
+```bash
+openclaw tasks notify <lookup> <done_only|state_changes|silent>
+```
+
+### `tasks audit`
+
+```bash
+openclaw tasks audit [--json]
+```
+
+Surfaces operational issues. Findings also appear in `openclaw status` when issues are detected.
+
+| Finding                   | Severity | Trigger                                               |
+| ------------------------- | -------- | ----------------------------------------------------- |
+| `stale_queued`            | warn     | Queued for more than 10 minutes                       |
+| `stale_running`           | error    | Running for more than 30 minutes                      |
+| `lost`                    | error    | Runtime-backed task ownership disappeared             |
+| `delivery_failed`         | warn     | Delivery failed and notify policy is not `silent`     |
+| `missing_cleanup`         | warn     | Terminal task with no cleanup timestamp               |
+| `inconsistent_timestamps` | warn     | Timeline violation (for example ended before started) |
+
+### `tasks maintenance`
+
+```bash
+openclaw tasks maintenance [--json]
+openclaw tasks maintenance --apply [--json]
+```
+
+Use this to preview or apply reconciliation, cleanup stamping, and pruning for
+tasks and Task Flow state.
+
+Reconciliation is runtime-aware:
+
+- ACP/subagent tasks check their backing child session.
+- Cron tasks check whether the cron runtime still owns the job.
+- Chat-backed CLI tasks check the owning live run context, not just the chat session row.
+
+Completion cleanup is also runtime-aware:
+
+- Subagent completion best-effort closes tracked browser tabs/processes for the child session before announce cleanup continues.
+- Isolated cron completion best-effort closes tracked browser tabs/processes for the cron session before the run fully tears down.
+- Isolated cron delivery waits out descendant subagent follow-up when needed and
+  suppresses stale parent acknowledgement text instead of announcing it.
+- Subagent completion delivery prefers the latest visible assistant text; if that is empty it falls back to sanitized latest tool/toolResult text, and timeout-only tool-call runs can collapse to a short partial-progress summary.
+- Cleanup failures do not mask the real task outcome.
+
+### `tasks flow list|show|cancel`
+
+```bash
+openclaw tasks flow list [--status <status>] [--json]
+openclaw tasks flow show <lookup> [--json]
+openclaw tasks flow cancel <lookup>
+```
+
+Use these when the orchestrating Task Flow is the thing you care about rather
+than one individual background task record.
+
+## Chat task board (`/tasks`)
+
+Use `/tasks` in any chat session to see background tasks linked to that session. The board shows
+active and recently completed tasks with runtime, status, timing, and progress or error detail.
+
+When the current session has no visible linked tasks, `/tasks` falls back to agent-local task counts
+so you still get an overview without leaking other-session details.
+
+For the full operator ledger, use the CLI: `openclaw tasks list`.
+
+## Status integration (task pressure)
+
+`openclaw status` includes an at-a-glance task summary:
+
+```
+Tasks: 3 queued · 2 running · 1 issues
+```
+
+The summary reports:
+
+- **active** — count of `queued` + `running`
+- **failures** — count of `failed` + `timed_out` + `lost`
+- **byRuntime** — breakdown by `acp`, `subagent`, `cron`, `cli`
+
+Both `/status` and the `session_status` tool use a cleanup-aware task snapshot: active tasks are
+preferred, stale completed rows are hidden, and recent failures only surface when no active work
+remains. This keeps the status card focused on what matters right now.
+
+## Storage and maintenance
+
+### Where tasks live
+
+Task records persist in SQLite at:
+
+```
+$OPENCLAW_STATE_DIR/tasks/runs.sqlite
+```
+
+The registry loads into memory at gateway start and syncs writes to SQLite for durability across restarts.
+
+### Automatic maintenance
+
+A sweeper runs every **60 seconds** and handles three things:
+
+1. **Reconciliation** — checks whether active tasks still have authoritative runtime backing. ACP/subagent tasks use child-session state, cron tasks use active-job ownership, and chat-backed CLI tasks use the owning run context. If that backing state is gone for more than 5 minutes, the task is marked `lost`.
+2. **Cleanup stamping** — sets a `cleanupAfter` timestamp on terminal tasks (endedAt + 7 days).
+3. **Pruning** — deletes records past their `cleanupAfter` date.
+
+**Retention**: terminal task records are kept for **7 days**, then automatically pruned. No configuration needed.
+
+## How tasks relate to other systems
+
+### Tasks and Task Flow
+
+[Task Flow](/automation/taskflow) is the flow orchestration layer above background tasks. A single flow may coordinate multiple tasks over its lifetime using managed or mirrored sync modes. Use `openclaw tasks` to inspect individual task records and `openclaw tasks flow` to inspect the orchestrating flow.
+
+See [Task Flow](/automation/taskflow) for details.
+
+### Tasks and cron
+
+A cron job **definition** lives in `~/.openclaw/cron/jobs.json`. **Every** cron execution creates a task record — both main-session and isolated. Main-session cron tasks default to `silent` notify policy so they track without generating notifications.
+
+See [Cron Jobs](/automation/cron-jobs).
+
+### Tasks and heartbeat
+
+Heartbeat runs are main-session turns — they do not create task records. When a task completes, it can trigger a heartbeat wake so you see the result promptly.
+
+See [Heartbeat](/gateway/heartbeat).
+
+### Tasks and sessions
+
+A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
+
+### Tasks and agent runs
+
+A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status — you do not need to manage the lifecycle manually.
+
+## Related
+
+- [Automation & Tasks](/automation) — all automation mechanisms at a glance
+- [Task Flow](/automation/taskflow) — flow orchestration above tasks
+- [Scheduled Tasks](/automation/cron-jobs) — scheduling background work
+- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
+- [CLI: Tasks](/cli/index#tasks) — CLI command reference
--- a/openclaw/docs/automation/troubleshooting.md
+++ b/openclaw/docs/automation/troubleshooting.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Automation Troubleshooting"
+---
+
+# Automation Troubleshooting
+
+This page moved to [Scheduled Tasks](/automation/cron-jobs#troubleshooting). See [Scheduled Tasks](/automation/cron-jobs#troubleshooting) for troubleshooting documentation.
--- a/openclaw/docs/automation/webhook.md
+++ b/openclaw/docs/automation/webhook.md
@ -0,0 +1,8 @@
+---
+summary: "Redirect to /automation/cron-jobs"
+title: "Webhooks"
+---
+
+# Webhooks
+
+This page moved to [Scheduled Tasks](/automation/cron-jobs#webhooks). See [Scheduled Tasks](/automation/cron-jobs#webhooks) for webhook documentation.
--- a/openclaw/docs/brave-search.md
+++ b/openclaw/docs/brave-search.md
@ -0,0 +1,103 @@
+---
+summary: "Brave Search API setup for web_search"
+read_when:
+  - You want to use Brave Search for web_search
+  - You need a BRAVE_API_KEY or plan details
+title: "Brave Search (legacy path)"
+---
+
+# Brave Search API
+
+OpenClaw supports Brave Search API as a `web_search` provider.
+
+## Get an API key
+
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
+2. In the dashboard, choose the **Search** plan and generate an API key.
+3. Store the key in config or set `BRAVE_API_KEY` in the Gateway environment.
+
+## Config example
+
+```json5
+{
+  plugins: {
+    entries: {
+      brave: {
+        config: {
+          webSearch: {
+            apiKey: "BRAVE_API_KEY_HERE",
+            mode: "web", // or "llm-context"
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "brave",
+        maxResults: 5,
+        timeoutSeconds: 30,
+      },
+    },
+  },
+}
+```
+
+Provider-specific Brave search settings now live under `plugins.entries.brave.config.webSearch.*`.
+Legacy `tools.web.search.apiKey` still loads through the compatibility shim, but it is no longer the canonical config path.
+
+`webSearch.mode` controls the Brave transport:
+
+- `web` (default): normal Brave web search with titles, URLs, and snippets
+- `llm-context`: Brave LLM Context API with pre-extracted text chunks and sources for grounding
+
+## Tool parameters
+
+| Parameter     | Description                                                         |
+| ------------- | ------------------------------------------------------------------- |
+| `query`       | Search query (required)                                             |
+| `count`       | Number of results to return (1-10, default: 5)                      |
+| `country`     | 2-letter ISO country code (e.g., "US", "DE")                        |
+| `language`    | ISO 639-1 language code for search results (e.g., "en", "de", "fr") |
+| `search_lang` | Brave search-language code (e.g., `en`, `en-gb`, `zh-hans`)         |
+| `ui_lang`     | ISO language code for UI elements                                   |
+| `freshness`   | Time filter: `day` (24h), `week`, `month`, or `year`                |
+| `date_after`  | Only results published after this date (YYYY-MM-DD)                 |
+| `date_before` | Only results published before this date (YYYY-MM-DD)                |
+
+**Examples:**
+
+```javascript
+// Country and language-specific search
+await web_search({
+  query: "renewable energy",
+  country: "DE",
+  language: "de",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "AI news",
+  freshness: "week",
+});
+
+// Date range search
+await web_search({
+  query: "AI developments",
+  date_after: "2024-01-01",
+  date_before: "2024-06-30",
+});
+```
+
+## Notes
+
+- OpenClaw uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits.
+- Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
+- The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service).
+- `llm-context` mode returns grounded source entries instead of the normal web-search snippet shape.
+- `llm-context` mode does not support `ui_lang`, `freshness`, `date_after`, or `date_before`.
+- `ui_lang` must include a region subtag like `en-US`.
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).
+
+See [Web tools](/tools/web) for the full web_search configuration.
--- a/openclaw/docs/channels/bluebubbles.md
+++ b/openclaw/docs/channels/bluebubbles.md
@ -0,0 +1,435 @@
+---
+summary: "iMessage via BlueBubbles macOS server (REST send/receive, typing, reactions, pairing, advanced actions)."
+read_when:
+  - Setting up BlueBubbles channel
+  - Troubleshooting webhook pairing
+  - Configuring iMessage on macOS
+title: "BlueBubbles"
+---
+
+# BlueBubbles (macOS REST)
+
+Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel.
+
+## Bundled plugin
+
+Current OpenClaw releases bundle BlueBubbles, so normal packaged builds do not
+need a separate `openclaw plugins install` step.
+
+## Overview
+
+- Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)).
+- Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync.
+- OpenClaw talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
+- Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
+- Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
+- Pairing/allowlist works the same way as other channels (`/channels/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
+- Reactions are surfaced as system events just like Slack/Telegram so agents can "mention" them before replying.
+- Advanced features: edit, unsend, reply threading, message effects, group management.
+
+## Quick start
+
+1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install)).
+2. In the BlueBubbles config, enable the web API and set a password.
+3. Run `openclaw onboard` and select BlueBubbles, or configure manually:
+
+   ```json5
+   {
+     channels: {
+       bluebubbles: {
+         enabled: true,
+         serverUrl: "http://192.168.1.100:1234",
+         password: "example-password",
+         webhookPath: "/bluebubbles-webhook",
+       },
+     },
+   }
+   ```
+
+4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
+5. Start the gateway; it will register the webhook handler and start pairing.
+
+Security note:
+
+- Always set a webhook password.
+- Webhook authentication is always required. OpenClaw rejects BlueBubbles webhook requests unless they include a password/guid that matches `channels.bluebubbles.password` (for example `?password=<password>` or `x-password`), regardless of loopback/proxy topology.
+- Password authentication is checked before reading/parsing full webhook bodies.
+
+## Keeping Messages.app alive (VM / headless setups)
+
+Some macOS VM / always-on setups can end up with Messages.app going “idle” (incoming events stop until the app is opened/foregrounded). A simple workaround is to **poke Messages every 5 minutes** using an AppleScript + LaunchAgent.
+
+### 1) Save the AppleScript
+
+Save this as:
+
+- `~/Scripts/poke-messages.scpt`
+
+Example script (non-interactive; does not steal focus):
+
+```applescript
+try
+  tell application "Messages"
+    if not running then
+      launch
+    end if
+
+    -- Touch the scripting interface to keep the process responsive.
+    set _chatCount to (count of chats)
+  end tell
+on error
+  -- Ignore transient failures (first-run prompts, locked session, etc).
+end try
+```
+
+### 2) Install a LaunchAgent
+
+Save this as:
+
+- `~/Library/LaunchAgents/com.user.poke-messages.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>com.user.poke-messages</string>
+
+    <key>ProgramArguments</key>
+    <array>
+      <string>/bin/bash</string>
+      <string>-lc</string>
+      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StartInterval</key>
+    <integer>300</integer>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/poke-messages.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/poke-messages.err</string>
+  </dict>
+</plist>
+```
+
+Notes:
+
+- This runs **every 300 seconds** and **on login**.
+- The first run may trigger macOS **Automation** prompts (`osascript` → Messages). Approve them in the same user session that runs the LaunchAgent.
+
+Load it:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
+launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
+```
+
+## Onboarding
+
+BlueBubbles is available in interactive onboarding:
+
+```
+openclaw onboard
+```
+
+The wizard prompts for:
+
+- **Server URL** (required): BlueBubbles server address (e.g., `http://192.168.1.100:1234`)
+- **Password** (required): API password from BlueBubbles Server settings
+- **Webhook path** (optional): Defaults to `/bluebubbles-webhook`
+- **DM policy**: pairing, allowlist, open, or disabled
+- **Allow list**: Phone numbers, emails, or chat targets
+
+You can also add BlueBubbles via CLI:
+
+```
+openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
+```
+
+## Access control (DMs + groups)
+
+DMs:
+
+- Default: `channels.bluebubbles.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `openclaw pairing list bluebubbles`
+  - `openclaw pairing approve bluebubbles <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
+
+Groups:
+
+- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
+- `channels.bluebubbles.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+
+### Contact name enrichment (macOS, optional)
+
+BlueBubbles group webhooks often only include raw participant addresses. If you want `GroupMembers` context to show local contact names instead, you can opt in to local Contacts enrichment on macOS:
+
+- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` enables the lookup. Default: `false`.
+- Lookups run only after group access, command authorization, and mention gating have allowed the message through.
+- Only unnamed phone participants are enriched.
+- Raw phone numbers remain as the fallback when no local match is found.
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      enrichGroupParticipantsFromContacts: true,
+    },
+  },
+}
+```
+
+### Mention gating (groups)
+
+BlueBubbles supports mention gating for group chats, matching iMessage/WhatsApp behavior:
+
+- Uses `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) to detect mentions.
+- When `requireMention` is enabled for a group, the agent only responds when mentioned.
+- Control commands from authorized senders bypass mention gating.
+
+Per-group configuration:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true }, // default for all groups
+        "iMessage;-;chat123": { requireMention: false }, // override for specific group
+      },
+    },
+  },
+}
+```
+
+### Command gating
+
+- Control commands (e.g., `/config`, `/model`) require authorization.
+- Uses `allowFrom` and `groupAllowFrom` to determine command authorization.
+- Authorized senders can run control commands even without mentioning in groups.
+
+## ACP conversation bindings
+
+BlueBubbles chats can be turned into durable ACP workspaces without changing the transport layer.
+
+Fast operator flow:
+
+- Run `/acp spawn codex --bind here` inside the DM or allowed group chat.
+- Future messages in that same BlueBubbles conversation route to the spawned ACP session.
+- `/new` and `/reset` reset the same bound ACP session in place.
+- `/acp close` closes the ACP session and removes the binding.
+
+Configured persistent bindings are also supported through top-level `bindings[]` entries with `type: "acp"` and `match.channel: "bluebubbles"`.
+
+`match.peer.id` can use any supported BlueBubbles target form:
+
+- normalized DM handle such as `+15555550123` or `user@example.com`
+- `chat_id:<id>`
+- `chat_guid:<guid>`
+- `chat_identifier:<identifier>`
+
+For stable group bindings, prefer `chat_id:*` or `chat_identifier:*`.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "bluebubbles",
+        accountId: "default",
+        peer: { kind: "dm", id: "+15555550123" },
+      },
+      acp: { label: "codex-imessage" },
+    },
+  ],
+}
+```
+
+See [ACP Agents](/tools/acp-agents) for shared ACP binding behavior.
+
+## Typing + read receipts
+
+- **Typing indicators**: Sent automatically before and during response generation.
+- **Read receipts**: Controlled by `channels.bluebubbles.sendReadReceipts` (default: `true`).
+- **Typing indicators**: OpenClaw sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable).
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      sendReadReceipts: false, // disable read receipts
+    },
+  },
+}
+```
+
+## Advanced actions
+
+BlueBubbles supports advanced message actions when enabled in config:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      actions: {
+        reactions: true, // tapbacks (default: true)
+        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
+        unsend: true, // unsend messages (macOS 13+)
+        reply: true, // reply threading by message GUID
+        sendWithEffect: true, // message effects (slam, loud, etc.)
+        renameGroup: true, // rename group chats
+        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
+        addParticipant: true, // add participants to groups
+        removeParticipant: true, // remove participants from groups
+        leaveGroup: true, // leave group chats
+        sendAttachment: true, // send attachments/media
+      },
+    },
+  },
+}
+```
+
+Available actions:
+
+- **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`)
+- **edit**: Edit a sent message (`messageId`, `text`)
+- **unsend**: Unsend a message (`messageId`)
+- **reply**: Reply to a specific message (`messageId`, `text`, `to`)
+- **sendWithEffect**: Send with iMessage effect (`text`, `to`, `effectId`)
+- **renameGroup**: Rename a group chat (`chatGuid`, `displayName`)
+- **setGroupIcon**: Set a group chat's icon/photo (`chatGuid`, `media`) — flaky on macOS 26 Tahoe (API may return success but the icon does not sync).
+- **addParticipant**: Add someone to a group (`chatGuid`, `address`)
+- **removeParticipant**: Remove someone from a group (`chatGuid`, `address`)
+- **leaveGroup**: Leave a group chat (`chatGuid`)
+- **upload-file**: Send media/files (`to`, `buffer`, `filename`, `asVoice`)
+  - Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 → CAF when sending voice memos.
+- Legacy alias: `sendAttachment` still works, but `upload-file` is the canonical action name.
+
+### Message IDs (short vs full)
+
+OpenClaw may surface _short_ message IDs (e.g., `1`, `2`) to save tokens.
+
+- `MessageSid` / `ReplyToId` can be short IDs.
+- `MessageSidFull` / `ReplyToIdFull` contain the provider full IDs.
+- Short IDs are in-memory; they can expire on restart or cache eviction.
+- Actions accept short or full `messageId`, but short IDs will error if no longer available.
+
+Use full IDs for durable automations and storage:
+
+- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
+- Context: `MessageSidFull` / `ReplyToIdFull` in inbound payloads
+
+See [Configuration](/gateway/configuration) for template variables.
+
+## Block streaming
+
+Control whether responses are sent as a single message or streamed in blocks:
+
+```json5
+{
+  channels: {
+    bluebubbles: {
+      blockStreaming: true, // enable block streaming (off by default)
+    },
+  },
+}
+```
+
+## Media + limits
+
+- Inbound attachments are downloaded and stored in the media cache.
+- Media cap via `channels.bluebubbles.mediaMaxMb` for inbound and outbound media (default: 8 MB).
+- Outbound text is chunked to `channels.bluebubbles.textChunkLimit` (default: 4000 chars).
+
+## Configuration reference
+
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+
+- `channels.bluebubbles.enabled`: Enable/disable the channel.
+- `channels.bluebubbles.serverUrl`: BlueBubbles REST API base URL.
+- `channels.bluebubbles.password`: API password.
+- `channels.bluebubbles.webhookPath`: Webhook endpoint path (default: `/bluebubbles-webhook`).
+- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
+- `channels.bluebubbles.allowFrom`: DM allowlist (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`).
+- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
+- `channels.bluebubbles.groupAllowFrom`: Group sender allowlist.
+- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: On macOS, optionally enrich unnamed group participants from local Contacts after gating passes. Default: `false`.
+- `channels.bluebubbles.groups`: Per-group config (`requireMention`, etc.).
+- `channels.bluebubbles.sendReadReceipts`: Send read receipts (default: `true`).
+- `channels.bluebubbles.blockStreaming`: Enable block streaming (default: `false`; required for streaming replies).
+- `channels.bluebubbles.textChunkLimit`: Outbound chunk size in chars (default: 4000).
+- `channels.bluebubbles.chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking.
+- `channels.bluebubbles.mediaMaxMb`: Inbound/outbound media cap in MB (default: 8).
+- `channels.bluebubbles.mediaLocalRoots`: Explicit allowlist of absolute local directories permitted for outbound local media paths. Local path sends are denied by default unless this is configured. Per-account override: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
+- `channels.bluebubbles.historyLimit`: Max group messages for context (0 disables).
+- `channels.bluebubbles.dmHistoryLimit`: DM history limit.
+- `channels.bluebubbles.actions`: Enable/disable specific actions.
+- `channels.bluebubbles.accounts`: Multi-account configuration.
+
+Related global options:
+
+- `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`).
+- `messages.responsePrefix`.
+
+## Addressing / delivery targets
+
+Prefer `chat_guid` for stable routing:
+
+- `chat_guid:iMessage;-;+15555550123` (preferred for groups)
+- `chat_id:123`
+- `chat_identifier:...`
+- Direct handles: `+15555550123`, `user@example.com`
+  - If a direct handle does not have an existing DM chat, OpenClaw will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled.
+
+## Security
+
+- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`.
+- Keep the API password and webhook endpoint secret (treat them like credentials).
+- There is no localhost bypass for BlueBubbles webhook auth. If you proxy webhook traffic, keep the BlueBubbles password on the request end-to-end. `gateway.trustedProxies` does not replace `channels.bluebubbles.password` here. See [Gateway security](/gateway/security#reverse-proxy-configuration).
+- Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
+
+## Troubleshooting
+
+- If typing/read events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`.
+- Pairing codes expire after one hour; use `openclaw pairing list bluebubbles` and `openclaw pairing approve bluebubbles <code>`.
+- Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it.
+- Edit/unsend require macOS 13+ and a compatible BlueBubbles server version. On macOS 26 (Tahoe), edit is currently broken due to private API changes.
+- Group icon updates can be flaky on macOS 26 (Tahoe): the API may return success but the new icon does not sync.
+- OpenClaw auto-hides known-broken actions based on the BlueBubbles server's macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`.
+- For status/health info: `openclaw status --all` or `openclaw status --deep`.
+
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/tools/plugin) guide.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/openclaw/docs/channels/broadcast-groups.md
+++ b/openclaw/docs/channels/broadcast-groups.md
@ -0,0 +1,442 @@
+---
+summary: "Broadcast a WhatsApp message to multiple agents"
+read_when:
+  - Configuring broadcast groups
+  - Debugging multi-agent replies in WhatsApp
+status: experimental
+title: "Broadcast Groups"
+---
+
+# Broadcast Groups
+
+**Status:** Experimental  
+**Version:** Added in 2026.1.9
+
+## Overview
+
+Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number.
+
+Current scope: **WhatsApp only** (web channel).
+
+Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when OpenClaw would normally reply (for example: on mention, depending on your group settings).
+
+## Use Cases
+
+### 1. Specialized Agent Teams
+
+Deploy multiple agents with atomic, focused responsibilities:
+
+```
+Group: "Development Team"
+Agents:
+  - CodeReviewer (reviews code snippets)
+  - DocumentationBot (generates docs)
+  - SecurityAuditor (checks for vulnerabilities)
+  - TestGenerator (suggests test cases)
+```
+
+Each agent processes the same message and provides its specialized perspective.
+
+### 2. Multi-Language Support
+
+```
+Group: "International Support"
+Agents:
+  - Agent_EN (responds in English)
+  - Agent_DE (responds in German)
+  - Agent_ES (responds in Spanish)
+```
+
+### 3. Quality Assurance Workflows
+
+```
+Group: "Customer Support"
+Agents:
+  - SupportAgent (provides answer)
+  - QAAgent (reviews quality, only responds if issues found)
+```
+
+### 4. Task Automation
+
+```
+Group: "Project Management"
+Agents:
+  - TaskTracker (updates task database)
+  - TimeLogger (logs time spent)
+  - ReportGenerator (creates summaries)
+```
+
+## Configuration
+
+### Basic Setup
+
+Add a top-level `broadcast` section (next to `bindings`). Keys are WhatsApp peer ids:
+
+- group chats: group JID (e.g. `120363403215116621@g.us`)
+- DMs: E.164 phone number (e.g. `+15551234567`)
+
+```json
+{
+  "broadcast": {
+    "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
+  }
+}
+```
+
+**Result:** When OpenClaw would reply in this chat, it will run all three agents.
+
+### Processing Strategy
+
+Control how agents process messages:
+
+#### Parallel (Default)
+
+All agents process simultaneously:
+
+```json
+{
+  "broadcast": {
+    "strategy": "parallel",
+    "120363403215116621@g.us": ["alfred", "baerbel"]
+  }
+}
+```
+
+#### Sequential
+
+Agents process in order (one waits for previous to finish):
+
+```json
+{
+  "broadcast": {
+    "strategy": "sequential",
+    "120363403215116621@g.us": ["alfred", "baerbel"]
+  }
+}
+```
+
+### Complete Example
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "code-reviewer",
+        "name": "Code Reviewer",
+        "workspace": "/path/to/code-reviewer",
+        "sandbox": { "mode": "all" }
+      },
+      {
+        "id": "security-auditor",
+        "name": "Security Auditor",
+        "workspace": "/path/to/security-auditor",
+        "sandbox": { "mode": "all" }
+      },
+      {
+        "id": "docs-generator",
+        "name": "Documentation Generator",
+        "workspace": "/path/to/docs-generator",
+        "sandbox": { "mode": "all" }
+      }
+    ]
+  },
+  "broadcast": {
+    "strategy": "parallel",
+    "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
+    "120363424282127706@g.us": ["support-en", "support-de"],
+    "+15555550123": ["assistant", "logger"]
+  }
+}
+```
+
+## How It Works
+
+### Message Flow
+
+1. **Incoming message** arrives in a WhatsApp group
+2. **Broadcast check**: System checks if peer ID is in `broadcast`
+3. **If in broadcast list**:
+   - All listed agents process the message
+   - Each agent has its own session key and isolated context
+   - Agents process in parallel (default) or sequentially
+4. **If not in broadcast list**:
+   - Normal routing applies (first matching binding)
+
+Note: broadcast groups do not bypass channel allowlists or group activation rules (mentions/commands/etc). They only change _which agents run_ when a message is eligible for processing.
+
+### Session Isolation
+
+Each agent in a broadcast group maintains completely separate:
+
+- **Session keys** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)
+- **Conversation history** (agent doesn't see other agents' messages)
+- **Workspace** (separate sandboxes if configured)
+- **Tool access** (different allow/deny lists)
+- **Memory/context** (separate IDENTITY.md, SOUL.md, etc.)
+- **Group context buffer** (recent group messages used for context) is shared per peer, so all broadcast agents see the same context when triggered
+
+This allows each agent to have:
+
+- Different personalities
+- Different tool access (e.g., read-only vs. read-write)
+- Different models (e.g., opus vs. sonnet)
+- Different skills installed
+
+### Example: Isolated Sessions
+
+In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`:
+
+**Alfred's context:**
+
+```
+Session: agent:alfred:whatsapp:group:120363403215116621@g.us
+History: [user message, alfred's previous responses]
+Workspace: /Users/user/openclaw-alfred/
+Tools: read, write, exec
+```
+
+**Bärbel's context:**
+
+```
+Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
+History: [user message, baerbel's previous responses]
+Workspace: /Users/user/openclaw-baerbel/
+Tools: read only
+```
+
+## Best Practices
+
+### 1. Keep Agents Focused
+
+Design each agent with a single, clear responsibility:
+
+```json
+{
+  "broadcast": {
+    "DEV_GROUP": ["formatter", "linter", "tester"]
+  }
+}
+```
+
+✅ **Good:** Each agent has one job  
+❌ **Bad:** One generic "dev-helper" agent
+
+### 2. Use Descriptive Names
+
+Make it clear what each agent does:
+
+```json
+{
+  "agents": {
+    "security-scanner": { "name": "Security Scanner" },
+    "code-formatter": { "name": "Code Formatter" },
+    "test-generator": { "name": "Test Generator" }
+  }
+}
+```
+
+### 3. Configure Different Tool Access
+
+Give agents only the tools they need:
+
+```json
+{
+  "agents": {
+    "reviewer": {
+      "tools": { "allow": ["read", "exec"] } // Read-only
+    },
+    "fixer": {
+      "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
+    }
+  }
+}
+```
+
+### 4. Monitor Performance
+
+With many agents, consider:
+
+- Using `"strategy": "parallel"` (default) for speed
+- Limiting broadcast groups to 5-10 agents
+- Using faster models for simpler agents
+
+### 5. Handle Failures Gracefully
+
+Agents fail independently. One agent's error doesn't block others:
+
+```
+Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
+Result: Agent A and C respond, Agent B logs error
+```
+
+## Compatibility
+
+### Providers
+
+Broadcast groups currently work with:
+
+- ✅ WhatsApp (implemented)
+- 🚧 Telegram (planned)
+- 🚧 Discord (planned)
+- 🚧 Slack (planned)
+
+### Routing
+
+Broadcast groups work alongside existing routing:
+
+```json
+{
+  "bindings": [
+    {
+      "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
+      "agentId": "alfred"
+    }
+  ],
+  "broadcast": {
+    "GROUP_B": ["agent1", "agent2"]
+  }
+}
+```
+
+- `GROUP_A`: Only alfred responds (normal routing)
+- `GROUP_B`: agent1 AND agent2 respond (broadcast)
+
+**Precedence:** `broadcast` takes priority over `bindings`.
+
+## Troubleshooting
+
+### Agents Not Responding
+
+**Check:**
+
+1. Agent IDs exist in `agents.list`
+2. Peer ID format is correct (e.g., `120363403215116621@g.us`)
+3. Agents are not in deny lists
+
+**Debug:**
+
+```bash
+tail -f ~/.openclaw/logs/gateway.log | grep broadcast
+```
+
+### Only One Agent Responding
+
+**Cause:** Peer ID might be in `bindings` but not `broadcast`.
+
+**Fix:** Add to broadcast config or remove from bindings.
+
+### Performance Issues
+
+**If slow with many agents:**
+
+- Reduce number of agents per group
+- Use lighter models (sonnet instead of opus)
+- Check sandbox startup time
+
+## Examples
+
+### Example 1: Code Review Team
+
+```json
+{
+  "broadcast": {
+    "strategy": "parallel",
+    "120363403215116621@g.us": [
+      "code-formatter",
+      "security-scanner",
+      "test-coverage",
+      "docs-checker"
+    ]
+  },
+  "agents": {
+    "list": [
+      {
+        "id": "code-formatter",
+        "workspace": "~/agents/formatter",
+        "tools": { "allow": ["read", "write"] }
+      },
+      {
+        "id": "security-scanner",
+        "workspace": "~/agents/security",
+        "tools": { "allow": ["read", "exec"] }
+      },
+      {
+        "id": "test-coverage",
+        "workspace": "~/agents/testing",
+        "tools": { "allow": ["read", "exec"] }
+      },
+      { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
+    ]
+  }
+}
+```
+
+**User sends:** Code snippet  
+**Responses:**
+
+- code-formatter: "Fixed indentation and added type hints"
+- security-scanner: "⚠️ SQL injection vulnerability in line 12"
+- test-coverage: "Coverage is 45%, missing tests for error cases"
+- docs-checker: "Missing docstring for function `process_data`"
+
+### Example 2: Multi-Language Support
+
+```json
+{
+  "broadcast": {
+    "strategy": "sequential",
+    "+15555550123": ["detect-language", "translator-en", "translator-de"]
+  },
+  "agents": {
+    "list": [
+      { "id": "detect-language", "workspace": "~/agents/lang-detect" },
+      { "id": "translator-en", "workspace": "~/agents/translate-en" },
+      { "id": "translator-de", "workspace": "~/agents/translate-de" }
+    ]
+  }
+}
+```
+
+## API Reference
+
+### Config Schema
+
+```typescript
+interface OpenClawConfig {
+  broadcast?: {
+    strategy?: "parallel" | "sequential";
+    [peerId: string]: string[];
+  };
+}
+```
+
+### Fields
+
+- `strategy` (optional): How to process agents
+  - `"parallel"` (default): All agents process simultaneously
+  - `"sequential"`: Agents process in array order
+- `[peerId]`: WhatsApp group JID, E.164 number, or other peer ID
+  - Value: Array of agent IDs that should process messages
+
+## Limitations
+
+1. **Max agents:** No hard limit, but 10+ agents may be slow
+2. **Shared context:** Agents don't see each other's responses (by design)
+3. **Message ordering:** Parallel responses may arrive in any order
+4. **Rate limits:** All agents count toward WhatsApp rate limits
+
+## Future Enhancements
+
+Planned features:
+
+- [ ] Shared context mode (agents see each other's responses)
+- [ ] Agent coordination (agents can signal each other)
+- [ ] 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)
--- a/openclaw/docs/channels/channel-routing.md
+++ b/openclaw/docs/channels/channel-routing.md
@ -0,0 +1,139 @@
+---
+summary: "Routing rules per channel (WhatsApp, Telegram, Discord, Slack) and shared context"
+read_when:
+  - Changing channel routing or inbox behavior
+title: "Channel Routing"
+---
+
+# Channels & routing
+
+OpenClaw routes replies **back to the channel where a message came from**. The
+model does not choose a channel; routing is deterministic and controlled by the
+host configuration.
+
+## Key terms
+
+- **Channel**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, plus extension channels. `webchat` is the internal WebChat UI channel and is not a configurable outbound channel.
+- **AccountId**: per‑channel account instance (when supported).
+- Optional channel default account: `channels.<channel>.defaultAccount` chooses
+  which account is used when an outbound path does not specify `accountId`.
+  - In multi-account setups, set an explicit default (`defaultAccount` or `accounts.default`) when two or more accounts are configured. Without it, fallback routing may pick the first normalized account ID.
+- **AgentId**: an isolated workspace + session store (“brain”).
+- **SessionKey**: the bucket key used to store context and control concurrency.
+
+## Session key shapes (examples)
+
+Direct messages collapse to the agent’s **main** session:
+
+- `agent:<agentId>:<mainKey>` (default: `agent:main:main`)
+
+Groups and channels remain isolated per channel:
+
+- Groups: `agent:<agentId>:<channel>:group:<id>`
+- Channels/rooms: `agent:<agentId>:<channel>:channel:<id>`
+
+Threads:
+
+- Slack/Discord threads append `:thread:<threadId>` to the base key.
+- Telegram forum topics embed `:topic:<topicId>` in the group key.
+
+Examples:
+
+- `agent:main:telegram:group:-1001234567890:topic:42`
+- `agent:main:discord:channel:123456:thread:987654`
+
+## Main DM route pinning
+
+When `session.dmScope` is `main`, direct messages may share one main session.
+To prevent the session’s `lastRoute` from being overwritten by non-owner DMs,
+OpenClaw infers a pinned owner from `allowFrom` when all of these are true:
+
+- `allowFrom` has exactly one non-wildcard entry.
+- The entry can be normalized to a concrete sender ID for that channel.
+- The inbound DM sender does not match that pinned owner.
+
+In that mismatch case, OpenClaw still records inbound session metadata, but it
+skips updating the main session `lastRoute`.
+
+## Routing rules (how an agent is chosen)
+
+Routing picks **one agent** for each inbound message:
+
+1. **Exact peer match** (`bindings` with `peer.kind` + `peer.id`).
+2. **Parent peer match** (thread inheritance).
+3. **Guild + roles match** (Discord) via `guildId` + `roles`.
+4. **Guild match** (Discord) via `guildId`.
+5. **Team match** (Slack) via `teamId`.
+6. **Account match** (`accountId` on the channel).
+7. **Channel match** (any account on that channel, `accountId: "*"`).
+8. **Default agent** (`agents.list[].default`, else first list entry, fallback to `main`).
+
+When a binding includes multiple match fields (`peer`, `guildId`, `teamId`, `roles`), **all provided fields must match** for that binding to apply.
+
+The matched agent determines which workspace and session store are used.
+
+## Broadcast groups (run multiple agents)
+
+Broadcast groups let you run **multiple agents** for the same peer **when OpenClaw would normally reply** (for example: in WhatsApp groups, after mention/activation gating).
+
+Config:
+
+```json5
+{
+  broadcast: {
+    strategy: "parallel",
+    "120363403215116621@g.us": ["alfred", "baerbel"],
+    "+15555550123": ["support", "logger"],
+  },
+}
+```
+
+See: [Broadcast Groups](/channels/broadcast-groups).
+
+## Config overview
+
+- `agents.list`: named agent definitions (workspace, model, etc.).
+- `bindings`: map inbound channels/accounts/peers to agents.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
+  },
+  bindings: [
+    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
+    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
+  ],
+}
+```
+
+## Session storage
+
+Session stores live under the state directory (default `~/.openclaw`):
+
+- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
+- JSONL transcripts live alongside the store
+
+You can override the store path via `session.store` and `{agentId}` templating.
+
+Gateway and ACP session discovery also scans disk-backed agent stores under the
+default `agents/` root and under templated `session.store` roots. Discovered
+stores must stay inside that resolved agent root and use a regular
+`sessions.json` file. Symlinks and out-of-root paths are ignored.
+
+## WebChat behavior
+
+WebChat attaches to the **selected agent** and defaults to the agent’s main
+session. Because of this, WebChat lets you see cross‑channel context for that
+agent in one place.
+
+## Reply context
+
+Inbound replies include:
+
+- `ReplyToId`, `ReplyToBody`, and `ReplyToSender` when available.
+- Quoted context is appended to `Body` as a `[Replying to ...]` block.
+
+This is consistent across channels.
--- a/openclaw/docs/channels/discord.md
+++ b/openclaw/docs/channels/discord.md
--- a/openclaw/docs/channels/feishu.md
+++ b/openclaw/docs/channels/feishu.md
@ -0,0 +1,439 @@
+---
+summary: "Feishu bot overview, features, and configuration"
+read_when:
+  - You want to connect a Feishu/Lark bot
+  - You are configuring the Feishu channel
+title: Feishu
+---
+
+# Feishu / Lark
+
+Feishu/Lark is an all-in-one collaboration platform where teams chat, share documents, manage calendars, and get work done together.
+
+**Status:** production-ready for bot DMs + group chats. WebSocket is the default mode; webhook mode is optional.
+
+---
+
+## Quick start
+
+> **Requires OpenClaw 2026.4.10 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
+
+<Steps>
+  <Step title="Run the channel setup wizard">
+  ```bash
+  openclaw channels login --channel feishu
+  ```
+  Scan the QR code with your Feishu/Lark mobile app to create a Feishu/Lark bot automatically.
+  </Step>
+  
+  <Step title="After setup completes, restart the gateway to apply the changes">
+  ```bash
+  openclaw gateway restart
+  ```
+  </Step>
+</Steps>
+
+---
+
+## Access control
+
+### Direct messages
+
+Configure `dmPolicy` to control who can DM the bot:
+
+- `"pairing"` — unknown users receive a pairing code; approve via CLI
+- `"allowlist"` — only users listed in `allowFrom` can chat (default: bot owner only)
+- `"open"` — allow all users
+- `"disabled"` — disable all DMs
+
+**Approve a pairing request:**
+
+```bash
+openclaw pairing list feishu
+openclaw pairing approve feishu <CODE>
+```
+
+### Group chats
+
+**Group policy** (`channels.feishu.groupPolicy`):
+
+| Value         | Behavior                                   |
+| ------------- | ------------------------------------------ |
+| `"open"`      | Respond to all messages in groups          |
+| `"allowlist"` | Only respond to groups in `groupAllowFrom` |
+| `"disabled"`  | Disable all group messages                 |
+
+Default: `allowlist`
+
+**Mention requirement** (`channels.feishu.requireMention`):
+
+- `true` — require @mention (default)
+- `false` — respond without @mention
+- Per-group override: `channels.feishu.groups.<chat_id>.requireMention`
+
+---
+
+## Group configuration examples
+
+### Allow all groups, no @mention required
+
+```json5
+{
+  channels: {
+    feishu: {
+      groupPolicy: "open",
+    },
+  },
+}
+```
+
+### Allow all groups, still require @mention
+
+```json5
+{
+  channels: {
+    feishu: {
+      groupPolicy: "open",
+      requireMention: true,
+    },
+  },
+}
+```
+
+### Allow specific groups only
+
+```json5
+{
+  channels: {
+    feishu: {
+      groupPolicy: "allowlist",
+      // Group IDs look like: oc_xxx
+      groupAllowFrom: ["oc_xxx", "oc_yyy"],
+    },
+  },
+}
+```
+
+### Restrict senders within a group
+
+```json5
+{
+  channels: {
+    feishu: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["oc_xxx"],
+      groups: {
+        oc_xxx: {
+          // User open_ids look like: ou_xxx
+          allowFrom: ["ou_user1", "ou_user2"],
+        },
+      },
+    },
+  },
+}
+```
+
+---
+
+## Get group/user IDs
+
+### Group IDs (`chat_id`, format: `oc_xxx`)
+
+Open the group in Feishu/Lark, click the menu icon in the top-right corner, and go to **Settings**. The group ID (`chat_id`) is listed on the settings page.
+
+![Get Group ID](/images/feishu-get-group-id.png)
+
+### User IDs (`open_id`, format: `ou_xxx`)
+
+Start the gateway, send a DM to the bot, then check the logs:
+
+```bash
+openclaw logs --follow
+```
+
+Look for `open_id` in the log output. You can also check pending pairing requests:
+
+```bash
+openclaw pairing list feishu
+```
+
+---
+
+## Common commands
+
+| Command   | Description                 |
+| --------- | --------------------------- |
+| `/status` | Show bot status             |
+| `/reset`  | Reset the current session   |
+| `/model`  | Show or switch the AI model |
+
+> Feishu/Lark does not support native slash-command menus, so send these as plain text messages.
+
+---
+
+## Troubleshooting
+
+### Bot does not respond in group chats
+
+1. Ensure the bot is added to the group
+2. Ensure you @mention the bot (required by default)
+3. Verify `groupPolicy` is not `"disabled"`
+4. Check logs: `openclaw logs --follow`
+
+### Bot does not receive messages
+
+1. Ensure the bot is published and approved in Feishu Open Platform / Lark Developer
+2. Ensure event subscription includes `im.message.receive_v1`
+3. Ensure **persistent connection** (WebSocket) is selected
+4. Ensure all required permission scopes are granted
+5. Ensure the gateway is running: `openclaw gateway status`
+6. Check logs: `openclaw logs --follow`
+
+### App Secret leaked
+
+1. Reset the App Secret in Feishu Open Platform / Lark Developer
+2. Update the value in your config
+3. Restart the gateway: `openclaw gateway restart`
+
+---
+
+## Advanced configuration
+
+### Multiple accounts
+
+```json5
+{
+  channels: {
+    feishu: {
+      defaultAccount: "main",
+      accounts: {
+        main: {
+          appId: "cli_xxx",
+          appSecret: "xxx",
+          name: "Primary bot",
+        },
+        backup: {
+          appId: "cli_yyy",
+          appSecret: "yyy",
+          name: "Backup bot",
+          enabled: false,
+        },
+      },
+    },
+  },
+}
+```
+
+`defaultAccount` controls which account is used when outbound APIs do not specify an `accountId`.
+
+### Message limits
+
+- `textChunkLimit` — outbound text chunk size (default: `2000` chars)
+- `mediaMaxMb` — media upload/download limit (default: `30` MB)
+
+### Streaming
+
+Feishu/Lark supports streaming replies via interactive cards. When enabled, the bot updates the card in real time as it generates text.
+
+```json5
+{
+  channels: {
+    feishu: {
+      streaming: true, // enable streaming card output (default: true)
+      blockStreaming: true, // enable block-level streaming (default: true)
+    },
+  },
+}
+```
+
+Set `streaming: false` to send the complete reply in one message.
+
+### Quota optimization
+
+Reduce the number of Feishu/Lark API calls with two optional flags:
+
+- `typingIndicator` (default `true`): set `false` to skip typing reaction calls
+- `resolveSenderNames` (default `true`): set `false` to skip sender profile lookups
+
+```json5
+{
+  channels: {
+    feishu: {
+      typingIndicator: false,
+      resolveSenderNames: false,
+    },
+  },
+}
+```
+
+### ACP sessions
+
+Feishu/Lark supports ACP for DMs and group thread messages. Feishu/Lark ACP is text-command driven — there are no native slash-command menus, so use `/acp ...` messages directly in the conversation.
+
+#### Persistent ACP binding
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: {
+            agent: "codex",
+            backend: "acpx",
+            mode: "persistent",
+            cwd: "/workspace/openclaw",
+          },
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "feishu",
+        accountId: "default",
+        peer: { kind: "direct", id: "ou_1234567890" },
+      },
+    },
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "feishu",
+        accountId: "default",
+        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
+      },
+      acp: { label: "codex-feishu-topic" },
+    },
+  ],
+}
+```
+
+#### Spawn ACP from chat
+
+In a Feishu/Lark DM or thread:
+
+```text
+/acp spawn codex --thread here
+```
+
+`--thread here` works for DMs and Feishu/Lark thread messages. Follow-up messages in the bound conversation route directly to that ACP session.
+
+### Multi-agent routing
+
+Use `bindings` to route Feishu/Lark DMs or groups to different agents.
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      { id: "agent-a", workspace: "/home/user/agent-a" },
+      { id: "agent-b", workspace: "/home/user/agent-b" },
+    ],
+  },
+  bindings: [
+    {
+      agentId: "agent-a",
+      match: {
+        channel: "feishu",
+        peer: { kind: "direct", id: "ou_xxx" },
+      },
+    },
+    {
+      agentId: "agent-b",
+      match: {
+        channel: "feishu",
+        peer: { kind: "group", id: "oc_zzz" },
+      },
+    },
+  ],
+}
+```
+
+Routing fields:
+
+- `match.channel`: `"feishu"`
+- `match.peer.kind`: `"direct"` (DM) or `"group"` (group chat)
+- `match.peer.id`: user Open ID (`ou_xxx`) or group ID (`oc_xxx`)
+
+See [Get group/user IDs](#get-groupuser-ids) for lookup tips.
+
+---
+
+## Configuration reference
+
+Full configuration: [Gateway configuration](/gateway/configuration)
+
+| Setting                                           | Description                                | Default          |
+| ------------------------------------------------- | ------------------------------------------ | ---------------- |
+| `channels.feishu.enabled`                         | Enable/disable the channel                 | `true`           |
+| `channels.feishu.domain`                          | API domain (`feishu` or `lark`)            | `feishu`         |
+| `channels.feishu.connectionMode`                  | Event transport (`websocket` or `webhook`) | `websocket`      |
+| `channels.feishu.defaultAccount`                  | Default account for outbound routing       | `default`        |
+| `channels.feishu.verificationToken`               | Required for webhook mode                  | —                |
+| `channels.feishu.encryptKey`                      | Required for webhook mode                  | —                |
+| `channels.feishu.webhookPath`                     | Webhook route path                         | `/feishu/events` |
+| `channels.feishu.webhookHost`                     | Webhook bind host                          | `127.0.0.1`      |
+| `channels.feishu.webhookPort`                     | Webhook bind port                          | `3000`           |
+| `channels.feishu.accounts.<id>.appId`             | App ID                                     | —                |
+| `channels.feishu.accounts.<id>.appSecret`         | App Secret                                 | —                |
+| `channels.feishu.accounts.<id>.domain`            | Per-account domain override                | `feishu`         |
+| `channels.feishu.dmPolicy`                        | DM policy                                  | `allowlist`      |
+| `channels.feishu.allowFrom`                       | DM allowlist (open_id list)                | [BotOwnerId]     |
+| `channels.feishu.groupPolicy`                     | Group policy                               | `allowlist`      |
+| `channels.feishu.groupAllowFrom`                  | Group allowlist                            | —                |
+| `channels.feishu.requireMention`                  | Require @mention in groups                 | `true`           |
+| `channels.feishu.groups.<chat_id>.requireMention` | Per-group @mention override                | inherited        |
+| `channels.feishu.groups.<chat_id>.enabled`        | Enable/disable a specific group            | `true`           |
+| `channels.feishu.textChunkLimit`                  | Message chunk size                         | `2000`           |
+| `channels.feishu.mediaMaxMb`                      | Media size limit                           | `30`             |
+| `channels.feishu.streaming`                       | Streaming card output                      | `true`           |
+| `channels.feishu.blockStreaming`                  | Block-level streaming                      | `true`           |
+| `channels.feishu.typingIndicator`                 | Send typing reactions                      | `true`           |
+| `channels.feishu.resolveSenderNames`              | Resolve sender display names               | `true`           |
+
+---
+
+## Supported message types
+
+### Receive
+
+- ✅ Text
+- ✅ Rich text (post)
+- ✅ Images
+- ✅ Files
+- ✅ Audio
+- ✅ Video/media
+- ✅ Stickers
+
+### Send
+
+- ✅ Text
+- ✅ Images
+- ✅ Files
+- ✅ Audio
+- ✅ Video/media
+- ✅ Interactive cards (including streaming updates)
+- ⚠️ Rich text (post-style formatting; doesn't support full Feishu/Lark authoring capabilities)
+
+### Threads and replies
+
+- ✅ Inline replies
+- ✅ Thread replies
+- ✅ Media replies stay thread-aware when replying to a thread message
+
+---
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/openclaw/docs/channels/googlechat.md
+++ b/openclaw/docs/channels/googlechat.md
@ -0,0 +1,270 @@
+---
+summary: "Google Chat app support status, capabilities, and configuration"
+read_when:
+  - Working on Google Chat channel features
+title: "Google Chat"
+---
+
+# Google Chat (Chat API)
+
+Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
+
+## Quick setup (beginner)
+
+1. Create a Google Cloud project and enable the **Google Chat API**.
+   - Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
+   - Enable the API if it is not already enabled.
+2. Create a **Service Account**:
+   - Press **Create Credentials** > **Service Account**.
+   - Name it whatever you want (e.g., `openclaw-chat`).
+   - Leave permissions blank (press **Continue**).
+   - Leave principals with access blank (press **Done**).
+3. Create and download the **JSON Key**:
+   - In the list of service accounts, click on the one you just created.
+   - Go to the **Keys** tab.
+   - Click **Add Key** > **Create new key**.
+   - Select **JSON** and press **Create**.
+4. Store the downloaded JSON file on your gateway host (e.g., `~/.openclaw/googlechat-service-account.json`).
+5. Create a Google Chat app in the [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
+   - Fill in the **Application info**:
+     - **App name**: (e.g. `OpenClaw`)
+     - **Avatar URL**: (e.g. `https://openclaw.ai/logo.png`)
+     - **Description**: (e.g. `Personal AI Assistant`)
+   - Enable **Interactive features**.
+   - Under **Functionality**, check **Join spaces and group conversations**.
+   - Under **Connection settings**, select **HTTP endpoint URL**.
+   - Under **Triggers**, select **Use a common HTTP endpoint URL for all triggers** and set it to your gateway's public URL followed by `/googlechat`.
+     - _Tip: Run `openclaw status` to find your gateway's public URL._
+   - Under **Visibility**, check **Make this Chat app available to specific people and groups in &lt;Your Domain&gt;**.
+   - Enter your email address (e.g. `user@example.com`) in the text box.
+   - Click **Save** at the bottom.
+6. **Enable the app status**:
+   - After saving, **refresh the page**.
+   - Look for the **App status** section (usually near the top or bottom after saving).
+   - Change the status to **Live - available to users**.
+   - Click **Save** again.
+7. Configure OpenClaw with the service account path + webhook audience:
+   - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
+   - Or config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
+8. Set the webhook audience type + value (matches your Chat app config).
+9. Start the gateway. Google Chat will POST to your webhook path.
+
+## Add to Google Chat
+
+Once the gateway is running and your email is added to the visibility list:
+
+1. Go to [Google Chat](https://chat.google.com/).
+2. Click the **+** (plus) icon next to **Direct Messages**.
+3. In the search bar (where you usually add people), type the **App name** you configured in the Google Cloud Console.
+   - **Note**: The bot will _not_ appear in the "Marketplace" browse list because it is a private app. You must search for it by name.
+4. Select your bot from the results.
+5. Click **Add** or **Chat** to start a 1:1 conversation.
+6. Send "Hello" to trigger the assistant!
+
+## Public URL (Webhook-only)
+
+Google Chat webhooks require a public HTTPS endpoint. For security, **only expose the `/googlechat` path** to the internet. Keep the OpenClaw dashboard and other sensitive endpoints on your private network.
+
+### Option A: Tailscale Funnel (Recommended)
+
+Use Tailscale Serve for the private dashboard and Funnel for the public webhook path. This keeps `/` private while exposing only `/googlechat`.
+
+1. **Check what address your gateway is bound to:**
+
+   ```bash
+   ss -tlnp | grep 18789
+   ```
+
+   Note the IP address (e.g., `127.0.0.1`, `0.0.0.0`, or your Tailscale IP like `100.x.x.x`).
+
+2. **Expose the dashboard to the tailnet only (port 8443):**
+
+   ```bash
+   # If bound to localhost (127.0.0.1 or 0.0.0.0):
+   tailscale serve --bg --https 8443 http://127.0.0.1:18789
+
+   # If bound to Tailscale IP only (e.g., 100.106.161.80):
+   tailscale serve --bg --https 8443 http://100.106.161.80:18789
+   ```
+
+3. **Expose only the webhook path publicly:**
+
+   ```bash
+   # If bound to localhost (127.0.0.1 or 0.0.0.0):
+   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
+
+   # If bound to Tailscale IP only (e.g., 100.106.161.80):
+   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
+   ```
+
+4. **Authorize the node for Funnel access:**
+   If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
+
+5. **Verify the configuration:**
+
+   ```bash
+   tailscale serve status
+   tailscale funnel status
+   ```
+
+Your public webhook URL will be:
+`https://<node-name>.<tailnet>.ts.net/googlechat`
+
+Your private dashboard stays tailnet-only:
+`https://<node-name>.<tailnet>.ts.net:8443/`
+
+Use the public URL (without `:8443`) in the Google Chat app config.
+
+> Note: This configuration persists across reboots. To remove it later, run `tailscale funnel reset` and `tailscale serve reset`.
+
+### Option B: Reverse Proxy (Caddy)
+
+If you use a reverse proxy like Caddy, only proxy the specific path:
+
+```caddy
+your-domain.com {
+    reverse_proxy /googlechat* localhost:18789
+}
+```
+
+With this config, any request to `your-domain.com/` will be ignored or returned as 404, while `your-domain.com/googlechat` is safely routed to OpenClaw.
+
+### Option C: Cloudflare Tunnel
+
+Configure your tunnel's ingress rules to only route the webhook path:
+
+- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
+- **Default Rule**: HTTP 404 (Not Found)
+
+## How it works
+
+1. Google Chat sends webhook POSTs to the gateway. Each request includes an `Authorization: Bearer <token>` header.
+   - OpenClaw verifies bearer auth before reading/parsing full webhook bodies when the header is present.
+   - Google Workspace Add-on requests that carry `authorizationEventObject.systemIdToken` in the body are supported via a stricter pre-auth body budget.
+2. OpenClaw verifies the token against the configured `audienceType` + `audience`:
+   - `audienceType: "app-url"` → audience is your HTTPS webhook URL.
+   - `audienceType: "project-number"` → audience is the Cloud project number.
+3. Messages are routed by space:
+   - DMs use session key `agent:<agentId>:googlechat:direct:<spaceId>`.
+   - Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
+4. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
+   - `openclaw pairing approve googlechat <code>`
+5. Group spaces require @-mention by default. Use `botUser` if mention detection needs the app’s user name.
+
+## Targets
+
+Use these identifiers for delivery and allowlists:
+
+- Direct messages: `users/<userId>` (recommended).
+- Raw email `name@example.com` is mutable and only used for direct allowlist matching when `channels.googlechat.dangerouslyAllowNameMatching: true`.
+- Deprecated: `users/<email>` is treated as a user id, not an email allowlist.
+- Spaces: `spaces/<spaceId>`.
+
+## Config highlights
+
+```json5
+{
+  channels: {
+    googlechat: {
+      enabled: true,
+      serviceAccountFile: "/path/to/service-account.json",
+      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
+      audienceType: "app-url",
+      audience: "https://gateway.example.com/googlechat",
+      webhookPath: "/googlechat",
+      botUser: "users/1234567890", // optional; helps mention detection
+      dm: {
+        policy: "pairing",
+        allowFrom: ["users/1234567890"],
+      },
+      groupPolicy: "allowlist",
+      groups: {
+        "spaces/AAAA": {
+          allow: true,
+          requireMention: true,
+          users: ["users/1234567890"],
+          systemPrompt: "Short answers only.",
+        },
+      },
+      actions: { reactions: true },
+      typingIndicator: "message",
+      mediaMaxMb: 20,
+    },
+  },
+}
+```
+
+Notes:
+
+- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
+- `serviceAccountRef` is also supported (env/file SecretRef), including per-account refs under `channels.googlechat.accounts.<id>.serviceAccountRef`.
+- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
+- `dangerouslyAllowNameMatching` re-enables mutable email principal matching for allowlists (break-glass compatibility mode).
+- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
+- Message actions expose `send` for text and `upload-file` for explicit attachment sends. `upload-file` accepts `media` / `filePath` / `path` plus optional `message`, `filename`, and thread targeting.
+- `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth).
+- Attachments are downloaded through the Chat API and stored in the media pipeline (size capped by `mediaMaxMb`).
+
+Secrets reference details: [Secrets Management](/gateway/secrets).
+
+## Troubleshooting
+
+### 405 Method Not Allowed
+
+If Google Cloud Logs Explorer shows errors like:
+
+```
+status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
+```
+
+This means the webhook handler isn't registered. Common causes:
+
+1. **Channel not configured**: The `channels.googlechat` section is missing from your config. Verify with:
+
+   ```bash
+   openclaw config get channels.googlechat
+   ```
+
+   If it returns "Config path not found", add the configuration (see [Config highlights](#config-highlights)).
+
+2. **Plugin not enabled**: Check plugin status:
+
+   ```bash
+   openclaw plugins list | grep googlechat
+   ```
+
+   If it shows "disabled", add `plugins.entries.googlechat.enabled: true` to your config.
+
+3. **Gateway not restarted**: After adding config, restart the gateway:
+
+   ```bash
+   openclaw gateway restart
+   ```
+
+Verify the channel is running:
+
+```bash
+openclaw channels status
+# Should show: Google Chat default: enabled, configured, ...
+```
+
+### Other issues
+
+- Check `openclaw channels status --probe` for auth errors or missing audience config.
+- If no messages arrive, confirm the Chat app's webhook URL + event subscriptions.
+- If mention gating blocks replies, set `botUser` to the app's user resource name and verify `requireMention`.
+- Use `openclaw logs --follow` while sending a test message to see if requests reach the gateway.
+
+Related docs:
+
+- [Gateway configuration](/gateway/configuration)
+- [Security](/gateway/security)
+- [Reactions](/tools/reactions)
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/openclaw/docs/channels/group-messages.md
+++ b/openclaw/docs/channels/group-messages.md
@ -0,0 +1,84 @@
+---
+summary: "Behavior and config for WhatsApp group message handling (mentionPatterns are shared across surfaces)"
+read_when:
+  - Changing group message rules or mentions
+title: "Group Messages"
+---
+
+# Group messages (WhatsApp web channel)
+
+Goal: let Clawd sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.
+
+Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/Slack/iMessage as well; this doc focuses on WhatsApp-specific behavior. For multi-agent setups, set `agents.list[].groupChat.mentionPatterns` per agent (or use `messages.groupChat.mentionPatterns` as a global fallback).
+
+## Current implementation (2025-12-03)
+
+- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token `NO_REPLY` / `no_reply`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
+- Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
+- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on`, `/trace on`, or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
+- Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.
+- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
+- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
+- Group system prompt: on the first turn of a group session (and whenever `/activation` changes the mode) we inject a short blurb into the system prompt like `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` If metadata isn’t available we still tell the agent it’s a group chat.
+
+## Config example (WhatsApp)
+
+Add a `groupChat` block to `~/.openclaw/openclaw.json` so display-name pings work even when WhatsApp strips the visual `@` in the text body:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          historyLimit: 50,
+          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
+        },
+      },
+    ],
+  },
+}
+```
+
+Notes:
+
+- The regexes are case-insensitive and use the same safe-regex guardrails as other config regex surfaces; invalid patterns and unsafe nested repetition are ignored.
+- WhatsApp still sends canonical mentions via `mentionedJids` when someone taps the contact, so the number fallback is rarely needed but is a useful safety net.
+
+### Activation command (owner-only)
+
+Use the group chat command:
+
+- `/activation mention`
+- `/activation always`
+
+Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.164 when unset) can change this. Send `/status` as a standalone message in the group to see the current activation mode.
+
+## How to use
+
+1. Add your WhatsApp account (the one running OpenClaw) to the group.
+2. Say `@openclaw …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
+3. The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
+4. Session-level directives (`/verbose on`, `/trace on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
+
+## Testing / verification
+
+- Manual smoke:
+  - Send an `@openclaw` ping in the group and confirm a reply that references the sender name.
+  - Send a second ping and verify the history block is included then cleared on the next turn.
+- Check gateway logs (run with `--verbose`) to see `inbound web message` entries showing `from: <groupJid>` and the `[from: …]` suffix.
+
+## Known considerations
+
+- Heartbeats are intentionally skipped for groups to avoid noisy broadcasts.
+- Echo suppression uses the combined batch string; if you send identical text twice without mentions, only the first will get a response.
+- Session store entries will appear as `agent:<agentId>:whatsapp:group:<jid>` in the session store (`~/.openclaw/agents/<agentId>/sessions/sessions.json` by default); a missing entry just means the group hasn’t triggered a run yet.
+- Typing indicators in groups follow `agents.defaults.typingMode` (default: `message` when unmentioned).
--- a/openclaw/docs/channels/groups.md
+++ b/openclaw/docs/channels/groups.md
@ -0,0 +1,413 @@
+---
+summary: "Group chat behavior across surfaces (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)"
+read_when:
+  - Changing group chat behavior or mention gating
+title: "Groups"
+---
+
+# Groups
+
+OpenClaw treats group chats consistently across surfaces: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
+
+## Beginner intro (2 minutes)
+
+OpenClaw “lives” on your own messaging accounts. There is no separate WhatsApp bot user.
+If **you** are in a group, OpenClaw can see that group and respond there.
+
+Default behavior:
+
+- Groups are restricted (`groupPolicy: "allowlist"`).
+- Replies require a mention unless you explicitly disable mention gating.
+
+Translation: allowlisted senders can trigger OpenClaw by mentioning it.
+
+> TL;DR
+>
+> - **DM access** is controlled by `*.allowFrom`.
+> - **Group access** is controlled by `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
+> - **Reply triggering** is controlled by mention gating (`requireMention`, `/activation`).
+
+Quick flow (what happens to a group message):
+
+```
+groupPolicy? disabled -> drop
+groupPolicy? allowlist -> group allowed? no -> drop
+requireMention? yes -> mentioned? no -> store for context only
+otherwise -> reply
+```
+
+## Context visibility and allowlists
+
+Two different controls are involved in group safety:
+
+- **Trigger authorization**: who can trigger the agent (`groupPolicy`, `groups`, `groupAllowFrom`, channel-specific allowlists).
+- **Context visibility**: what supplemental context is injected into the model (reply text, quotes, thread history, forwarded metadata).
+
+By default, OpenClaw prioritizes normal chat behavior and keeps context mostly as received. This means allowlists primarily decide who can trigger actions, not a universal redaction boundary for every quoted or historical snippet.
+
+Current behavior is channel-specific:
+
+- Some channels already apply sender-based filtering for supplemental context in specific paths (for example Slack thread seeding, Matrix reply/thread lookups).
+- Other channels still pass quote/reply/forward context through as received.
+
+Hardening direction (planned):
+
+- `contextVisibility: "all"` (default) keeps current as-received behavior.
+- `contextVisibility: "allowlist"` filters supplemental context to allowlisted senders.
+- `contextVisibility: "allowlist_quote"` is `allowlist` plus one explicit quote/reply exception.
+
+Until this hardening model is implemented consistently across channels, expect differences by surface.
+
+![Group message flow](/images/groups-flow.svg)
+
+If you want...
+
+| Goal                                         | What to set                                                |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| Allow all groups but only reply on @mentions | `groups: { "*": { requireMention: true } }`                |
+| Disable all group replies                    | `groupPolicy: "disabled"`                                  |
+| Only specific groups                         | `groups: { "<group-id>": { ... } }` (no `"*"` key)         |
+| Only you can trigger in groups               | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
+
+## Session keys
+
+- Group sessions use `agent:<agentId>:<channel>:group:<id>` session keys (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
+- Telegram forum topics add `:topic:<threadId>` to the group id so each topic has its own session.
+- Direct chats use the main session (or per-sender if configured).
+- Heartbeats are skipped for group sessions.
+
+<a id="pattern-personal-dms-public-groups-single-agent"></a>
+
+## Pattern: personal DMs + public groups (single agent)
+
+Yes — this works well if your “personal” traffic is **DMs** and your “public” traffic is **groups**.
+
+Why: in single-agent mode, DMs typically land in the **main** session key (`agent:main:main`), while groups always use **non-main** session keys (`agent:main:<channel>:group:<id>`). If you enable sandboxing with `mode: "non-main"`, those group sessions run in Docker while your main DM session stays on-host.
+
+This gives you one agent “brain” (shared workspace + memory), but two execution postures:
+
+- **DMs**: full tools (host)
+- **Groups**: sandbox + restricted tools (Docker)
+
+> If you need truly separate workspaces/personas (“personal” and “public” must never mix), use a second agent + bindings. See [Multi-Agent Routing](/concepts/multi-agent).
+
+Example (DMs on host, groups sandboxed + messaging-only tools):
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main", // groups/channels are non-main -> sandboxed
+        scope: "session", // strongest isolation (one container per group/channel)
+        workspaceAccess: "none",
+      },
+    },
+  },
+  tools: {
+    sandbox: {
+      tools: {
+        // If allow is non-empty, everything else is blocked (deny still wins).
+        allow: ["group:messaging", "group:sessions"],
+        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
+      },
+    },
+  },
+}
+```
+
+Want “groups can only see folder X” instead of “no host access”? Keep `workspaceAccess: "none"` and mount only allowlisted paths into the sandbox:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+        docker: {
+          binds: [
+            // hostPath:containerPath:mode
+            "/home/user/FriendsShared:/data:ro",
+          ],
+        },
+      },
+    },
+  },
+}
+```
+
+Related:
+
+- Configuration keys and defaults: [Gateway configuration](/gateway/configuration-reference#agentsdefaultssandbox)
+- Debugging why a tool is blocked: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
+- Bind mounts details: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
+
+## Display labels
+
+- UI labels use `displayName` when available, formatted as `<channel>:<token>`.
+- `#room` is reserved for rooms/channels; group chats use `g-<slug>` (lowercase, spaces -> `-`, keep `#@+._-`).
+
+## Group policy
+
+Control how group/room messages are handled per channel:
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
+      groupAllowFrom: ["+15551234567"],
+    },
+    telegram: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
+    },
+    signal: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["+15551234567"],
+    },
+    imessage: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["chat_id:123"],
+    },
+    msteams: {
+      groupPolicy: "disabled",
+      groupAllowFrom: ["user@org.com"],
+    },
+    discord: {
+      groupPolicy: "allowlist",
+      guilds: {
+        GUILD_ID: { channels: { help: { allow: true } } },
+      },
+    },
+    slack: {
+      groupPolicy: "allowlist",
+      channels: { "#general": { allow: true } },
+    },
+    matrix: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["@owner:example.org"],
+      groups: {
+        "!roomId:example.org": { enabled: true },
+        "#alias:example.org": { enabled: true },
+      },
+    },
+  },
+}
+```
+
+| Policy        | Behavior                                                     |
+| ------------- | ------------------------------------------------------------ |
+| `"open"`      | Groups bypass allowlists; mention-gating still applies.      |
+| `"disabled"`  | Block all group messages entirely.                           |
+| `"allowlist"` | Only allow groups/rooms that match the configured allowlist. |
+
+Notes:
+
+- `groupPolicy` is separate from mention-gating (which requires @mentions).
+- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use `groupAllowFrom` (fallback: explicit `allowFrom`).
+- DM pairing approvals (`*-allowFrom` store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
+- Discord: allowlist uses `channels.discord.guilds.<id>.channels`.
+- Slack: allowlist uses `channels.slack.channels`.
+- Matrix: allowlist uses `channels.matrix.groups`. Prefer room IDs or aliases; joined-room name lookup is best-effort, and unresolved names are ignored at runtime. Use `channels.matrix.groupAllowFrom` to restrict senders; per-room `users` allowlists are also supported.
+- Group DMs are controlled separately (`channels.discord.dm.*`, `channels.slack.dm.*`).
+- Telegram allowlist can match user IDs (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) or usernames (`"@alice"` or `"alice"`); prefixes are case-insensitive.
+- Default is `groupPolicy: "allowlist"`; if your group allowlist is empty, group messages are blocked.
+- Runtime safety: when a provider block is completely missing (`channels.<provider>` absent), group policy falls back to a fail-closed mode (typically `allowlist`) instead of inheriting `channels.defaults.groupPolicy`.
+
+Quick mental model (evaluation order for group messages):
+
+1. `groupPolicy` (open/disabled/allowlist)
+2. group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist)
+3. mention gating (`requireMention`, `/activation`)
+
+## Mention gating (default)
+
+Group messages require a mention unless overridden per group. Defaults live per subsystem under `*.groups."*"`.
+
+Replying to a bot message counts as an implicit mention when the channel
+supports reply metadata. Quoting a bot message can also count as an implicit
+mention on channels that expose quote metadata. Current built-in cases include
+Telegram, WhatsApp, Slack, Discord, Microsoft Teams, and ZaloUser.
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "*": { requireMention: true },
+        "123@g.us": { requireMention: false },
+      },
+    },
+    telegram: {
+      groups: {
+        "*": { requireMention: true },
+        "123456789": { requireMention: false },
+      },
+    },
+    imessage: {
+      groups: {
+        "*": { requireMention: true },
+        "123": { requireMention: false },
+      },
+    },
+  },
+  agents: {
+    list: [
+      {
+        id: "main",
+        groupChat: {
+          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
+          historyLimit: 50,
+        },
+      },
+    ],
+  },
+}
+```
+
+Notes:
+
+- `mentionPatterns` are case-insensitive safe regex patterns; invalid patterns and unsafe nested-repetition forms are ignored.
+- Surfaces that provide explicit mentions still pass; patterns are a fallback.
+- Per-agent override: `agents.list[].groupChat.mentionPatterns` (useful when multiple agents share a group).
+- Mention gating is only enforced when mention detection is possible (native mentions or `mentionPatterns` are configured).
+- Discord defaults live in `channels.discord.guilds."*"` (overridable per guild/channel).
+- Group history context is wrapped uniformly across channels and is **pending-only** (messages skipped due to mention gating); use `messages.groupChat.historyLimit` for the global default and `channels.<channel>.historyLimit` (or `channels.<channel>.accounts.*.historyLimit`) for overrides. Set `0` to disable.
+
+## Group/channel tool restrictions (optional)
+
+Some channel configs support restricting which tools are available **inside a specific group/room/channel**.
+
+- `tools`: allow/deny tools for the whole group.
+- `toolsBySender`: per-sender overrides within the group.
+  Use explicit key prefixes:
+  `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, and `"*"` wildcard.
+  Legacy unprefixed keys are still accepted and matched as `id:` only.
+
+Resolution order (most specific wins):
+
+1. group/channel `toolsBySender` match
+2. group/channel `tools`
+3. default (`"*"`) `toolsBySender` match
+4. default (`"*"`) `tools`
+
+Example (Telegram):
+
+```json5
+{
+  channels: {
+    telegram: {
+      groups: {
+        "*": { tools: { deny: ["exec"] } },
+        "-1001234567890": {
+          tools: { deny: ["exec", "read", "write"] },
+          toolsBySender: {
+            "id:123456789": { alsoAllow: ["exec"] },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Group/channel tool restrictions are applied in addition to global/agent tool policy (deny still wins).
+- Some channels use different nesting for rooms/channels (e.g., Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
+
+## Group allowlists
+
+When `channels.whatsapp.groups`, `channels.telegram.groups`, or `channels.imessage.groups` is configured, the keys act as a group allowlist. Use `"*"` to allow all groups while still setting default mention behavior.
+
+Common confusion: DM pairing approval is not the same as group authorization.
+For channels that support DM pairing, the pairing store unlocks DMs only. Group commands still require explicit group sender authorization from config allowlists such as `groupAllowFrom` or the documented config fallback for that channel.
+
+Common intents (copy/paste):
+
+1. Disable all group replies
+
+```json5
+{
+  channels: { whatsapp: { groupPolicy: "disabled" } },
+}
+```
+
+2. Allow only specific groups (WhatsApp)
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: {
+        "123@g.us": { requireMention: true },
+        "456@g.us": { requireMention: false },
+      },
+    },
+  },
+}
+```
+
+3. Allow all groups but require mention (explicit)
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groups: { "*": { requireMention: true } },
+    },
+  },
+}
+```
+
+4. Only the owner can trigger in groups (WhatsApp)
+
+```json5
+{
+  channels: {
+    whatsapp: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15551234567"],
+      groups: { "*": { requireMention: true } },
+    },
+  },
+}
+```
+
+## Activation (owner-only)
+
+Group owners can toggle per-group activation:
+
+- `/activation mention`
+- `/activation always`
+
+Owner is determined by `channels.whatsapp.allowFrom` (or the bot’s self E.164 when unset). Send the command as a standalone message. Other surfaces currently ignore `/activation`.
+
+## Context fields
+
+Group inbound payloads set:
+
+- `ChatType=group`
+- `GroupSubject` (if known)
+- `GroupMembers` (if known)
+- `WasMentioned` (mention gating result)
+- Telegram forum topics also include `MessageThreadId` and `IsForum`.
+
+Channel specific notes:
+
+- BlueBubbles can optionally enrich unnamed macOS group participants from the local Contacts database before populating `GroupMembers`. This is off by default and only runs after normal group gating passes.
+
+The agent system prompt includes a group intro on the first turn of a new group session. It reminds the model to respond like a human, avoid Markdown tables, minimize empty lines and follow normal chat spacing, and avoid typing literal `\n` sequences.
+
+## iMessage specifics
+
+- Prefer `chat_id:<id>` when routing or allowlisting.
+- List chats: `imsg chats --limit 20`.
+- Group replies always go back to the same `chat_id`.
+
+## WhatsApp specifics
+
+See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
--- a/openclaw/docs/channels/imessage.md
+++ b/openclaw/docs/channels/imessage.md
@ -0,0 +1,427 @@
+---
+summary: "Legacy iMessage support via imsg (JSON-RPC over stdio). New setups should use BlueBubbles."
+read_when:
+  - Setting up iMessage support
+  - Debugging iMessage send/receive
+title: "iMessage"
+---
+
+# iMessage (legacy: imsg)
+
+<Warning>
+For new iMessage deployments, use <a href="/channels/bluebubbles">BlueBubbles</a>.
+
+The `imsg` integration is legacy and may be removed in a future release.
+</Warning>
+
+Status: legacy external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port).
+
+<CardGroup cols={3}>
+  <Card title="BlueBubbles (recommended)" icon="message-circle" href="/channels/bluebubbles">
+    Preferred iMessage path for new setups.
+  </Card>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    iMessage DMs default to pairing mode.
+  </Card>
+  <Card title="Configuration reference" icon="settings" href="/gateway/configuration-reference#imessage">
+    Full iMessage field reference.
+  </Card>
+</CardGroup>
+
+## Quick setup
+
+<Tabs>
+  <Tab title="Local Mac (fast path)">
+    <Steps>
+      <Step title="Install and verify imsg">
+
+```bash
+brew install steipete/tap/imsg
+imsg rpc --help
+```
+
+      </Step>
+
+      <Step title="Configure OpenClaw">
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "/usr/local/bin/imsg",
+      dbPath: "/Users/<you>/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+      </Step>
+
+      <Step title="Start gateway">
+
+```bash
+openclaw gateway
+```
+
+      </Step>
+
+      <Step title="Approve first DM pairing (default dmPolicy)">
+
+```bash
+openclaw pairing list imessage
+openclaw pairing approve imessage <CODE>
+```
+
+        Pairing requests expire after 1 hour.
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Remote Mac over SSH">
+    OpenClaw only requires a stdio-compatible `cliPath`, so you can point `cliPath` at a wrapper script that SSHes to a remote Mac and runs `imsg`.
+
+```bash
+#!/usr/bin/env bash
+exec ssh -T gateway-host imsg "$@"
+```
+
+    Recommended config when attachments are enabled:
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "~/.openclaw/scripts/imsg-ssh",
+      remoteHost: "user@gateway-host", // used for SCP attachment fetches
+      includeAttachments: true,
+      // Optional: override allowed attachment roots.
+      // Defaults include /Users/*/Library/Messages/Attachments
+      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
+      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
+    },
+  },
+}
+```
+
+    If `remoteHost` is not set, OpenClaw attempts to auto-detect it by parsing the SSH wrapper script.
+    `remoteHost` must be `host` or `user@host` (no spaces or SSH options).
+    OpenClaw uses strict host-key checking for SCP, so the relay host key must already exist in `~/.ssh/known_hosts`.
+    Attachment paths are validated against allowed roots (`attachmentRoots` / `remoteAttachmentRoots`).
+
+  </Tab>
+</Tabs>
+
+## Requirements and permissions (macOS)
+
+- Messages must be signed in on the Mac running `imsg`.
+- Full Disk Access is required for the process context running OpenClaw/`imsg` (Messages DB access).
+- Automation permission is required to send messages through Messages.app.
+
+<Tip>
+Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:
+
+```bash
+imsg chats --limit 1
+# or
+imsg send <handle> "test"
+```
+
+</Tip>
+
+## Access control and routing
+
+<Tabs>
+  <Tab title="DM policy">
+    `channels.imessage.dmPolicy` controls direct messages:
+
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `allowFrom` to include `"*"`)
+    - `disabled`
+
+    Allowlist field: `channels.imessage.allowFrom`.
+
+    Allowlist entries can be handles or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
+
+  </Tab>
+
+  <Tab title="Group policy + mentions">
+    `channels.imessage.groupPolicy` controls group handling:
+
+    - `allowlist` (default when configured)
+    - `open`
+    - `disabled`
+
+    Group sender allowlist: `channels.imessage.groupAllowFrom`.
+
+    Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks fall back to `allowFrom` when available.
+    Runtime note: if `channels.imessage` is completely missing, runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).
+
+    Mention gating for groups:
+
+    - iMessage has no native mention metadata
+    - mention detection uses regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - with no configured patterns, mention gating cannot be enforced
+
+    Control commands from authorized senders can bypass mention gating in groups.
+
+  </Tab>
+
+  <Tab title="Sessions and deterministic replies">
+    - DMs use direct routing; groups use group routing.
+    - With default `session.dmScope=main`, iMessage DMs collapse into the agent main session.
+    - Group sessions are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
+    - Replies route back to iMessage using originating channel/target metadata.
+
+    Group-ish thread behavior:
+
+    Some multi-participant iMessage threads can arrive with `is_group=false`.
+    If that `chat_id` is explicitly configured under `channels.imessage.groups`, OpenClaw treats it as group traffic (group gating + group session isolation).
+
+  </Tab>
+</Tabs>
+
+## ACP conversation bindings
+
+Legacy iMessage chats can also be bound to ACP sessions.
+
+Fast operator flow:
+
+- Run `/acp spawn codex --bind here` inside the DM or allowed group chat.
+- Future messages in that same iMessage conversation route to the spawned ACP session.
+- `/new` and `/reset` reset the same bound ACP session in place.
+- `/acp close` closes the ACP session and removes the binding.
+
+Configured persistent bindings are supported through top-level `bindings[]` entries with `type: "acp"` and `match.channel: "imessage"`.
+
+`match.peer.id` can use:
+
+- normalized DM handle such as `+15555550123` or `user@example.com`
+- `chat_id:<id>` (recommended for stable group bindings)
+- `chat_guid:<guid>`
+- `chat_identifier:<identifier>`
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: { agent: "codex", backend: "acpx", mode: "persistent" },
+        },
+      },
+    ],
+  },
+  bindings: [
+    {
+      type: "acp",
+      agentId: "codex",
+      match: {
+        channel: "imessage",
+        accountId: "default",
+        peer: { kind: "group", id: "chat_id:123" },
+      },
+      acp: { label: "codex-group" },
+    },
+  ],
+}
+```
+
+See [ACP Agents](/tools/acp-agents) for shared ACP binding behavior.
+
+## Deployment patterns
+
+<AccordionGroup>
+  <Accordion title="Dedicated bot macOS user (separate iMessage identity)">
+    Use a dedicated Apple ID and macOS user so bot traffic is isolated from your personal Messages profile.
+
+    Typical flow:
+
+    1. Create/sign in a dedicated macOS user.
+    2. Sign into Messages with the bot Apple ID in that user.
+    3. Install `imsg` in that user.
+    4. Create SSH wrapper so OpenClaw can run `imsg` in that user context.
+    5. Point `channels.imessage.accounts.<id>.cliPath` and `.dbPath` to that user profile.
+
+    First run may require GUI approvals (Automation + Full Disk Access) in that bot user session.
+
+  </Accordion>
+
+  <Accordion title="Remote Mac over Tailscale (example)">
+    Common topology:
+
+    - gateway runs on Linux/VM
+    - iMessage + `imsg` runs on a Mac in your tailnet
+    - `cliPath` wrapper uses SSH to run `imsg`
+    - `remoteHost` enables SCP attachment fetches
+
+    Example:
+
+```json5
+{
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "~/.openclaw/scripts/imsg-ssh",
+      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
+      includeAttachments: true,
+      dbPath: "/Users/bot/Library/Messages/chat.db",
+    },
+  },
+}
+```
+
+```bash
+#!/usr/bin/env bash
+exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
+```
+
+    Use SSH keys so both SSH and SCP are non-interactive.
+    Ensure the host key is trusted first (for example `ssh bot@mac-mini.tailnet-1234.ts.net`) so `known_hosts` is populated.
+
+  </Accordion>
+
+  <Accordion title="Multi-account pattern">
+    iMessage supports per-account config under `channels.imessage.accounts`.
+
+    Each account can override fields such as `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, history settings, and attachment root allowlists.
+
+  </Accordion>
+</AccordionGroup>
+
+## Media, chunking, and delivery targets
+
+<AccordionGroup>
+  <Accordion title="Attachments and media">
+    - inbound attachment ingestion is optional: `channels.imessage.includeAttachments`
+    - remote attachment paths can be fetched via SCP when `remoteHost` is set
+    - attachment paths must match allowed roots:
+      - `channels.imessage.attachmentRoots` (local)
+      - `channels.imessage.remoteAttachmentRoots` (remote SCP mode)
+      - default root pattern: `/Users/*/Library/Messages/Attachments`
+    - SCP uses strict host-key checking (`StrictHostKeyChecking=yes`)
+    - outbound media size uses `channels.imessage.mediaMaxMb` (default 16 MB)
+  </Accordion>
+
+  <Accordion title="Outbound chunking">
+    - text chunk limit: `channels.imessage.textChunkLimit` (default 4000)
+    - chunk mode: `channels.imessage.chunkMode`
+      - `length` (default)
+      - `newline` (paragraph-first splitting)
+  </Accordion>
+
+  <Accordion title="Addressing formats">
+    Preferred explicit targets:
+
+    - `chat_id:123` (recommended for stable routing)
+    - `chat_guid:...`
+    - `chat_identifier:...`
+
+    Handle targets are also supported:
+
+    - `imessage:+1555...`
+    - `sms:+1555...`
+    - `user@example.com`
+
+```bash
+imsg chats --limit 20
+```
+
+  </Accordion>
+</AccordionGroup>
+
+## Config writes
+
+iMessage allows channel-initiated config writes by default (for `/config set|unset` when `commands.config: true`).
+
+Disable:
+
+```json5
+{
+  channels: {
+    imessage: {
+      configWrites: false,
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="imsg not found or RPC unsupported">
+    Validate the binary and RPC support:
+
+```bash
+imsg rpc --help
+openclaw channels status --probe
+```
+
+    If probe reports RPC unsupported, update `imsg`.
+
+  </Accordion>
+
+  <Accordion title="DMs are ignored">
+    Check:
+
+    - `channels.imessage.dmPolicy`
+    - `channels.imessage.allowFrom`
+    - pairing approvals (`openclaw pairing list imessage`)
+
+  </Accordion>
+
+  <Accordion title="Group messages are ignored">
+    Check:
+
+    - `channels.imessage.groupPolicy`
+    - `channels.imessage.groupAllowFrom`
+    - `channels.imessage.groups` allowlist behavior
+    - mention pattern configuration (`agents.list[].groupChat.mentionPatterns`)
+
+  </Accordion>
+
+  <Accordion title="Remote attachments fail">
+    Check:
+
+    - `channels.imessage.remoteHost`
+    - `channels.imessage.remoteAttachmentRoots`
+    - SSH/SCP key auth from the gateway host
+    - host key exists in `~/.ssh/known_hosts` on the gateway host
+    - remote path readability on the Mac running Messages
+
+  </Accordion>
+
+  <Accordion title="macOS permission prompts were missed">
+    Re-run in an interactive GUI terminal in the same user/session context and approve prompts:
+
+```bash
+imsg chats --limit 1
+imsg send <handle> "test"
+```
+
+    Confirm Full Disk Access + Automation are granted for the process context that runs OpenClaw/`imsg`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+- [Configuration reference - iMessage](/gateway/configuration-reference#imessage)
+- [Gateway configuration](/gateway/configuration)
+- [Pairing](/channels/pairing)
+- [BlueBubbles](/channels/bluebubbles)
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/openclaw/docs/channels/index.md
+++ b/openclaw/docs/channels/index.md
@ -0,0 +1,50 @@
+---
+summary: "Messaging platforms OpenClaw can connect to"
+read_when:
+  - You want to choose a chat channel for OpenClaw
+  - You need a quick overview of supported messaging platforms
+title: "Chat Channels"
+---
+
+# Chat Channels
+
+OpenClaw can talk to you on any chat app you already use. Each channel connects via the Gateway.
+Text is supported everywhere; media and reactions vary by channel.
+
+## Supported channels
+
+- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (bundled plugin; edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
+- [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
+- [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (bundled plugin).
+- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
+- [iMessage (legacy)](/channels/imessage) — Legacy macOS integration via imsg CLI (deprecated, use BlueBubbles for new setups).
+- [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls.
+- [LINE](/channels/line) — LINE Messaging API bot (bundled plugin).
+- [Matrix](/channels/matrix) — Matrix protocol (bundled plugin).
+- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (bundled plugin).
+- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (bundled plugin).
+- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (bundled plugin).
+- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (bundled plugin).
+- [QQ Bot](/channels/qqbot) — QQ Bot API; private chat, group chat, and rich media (bundled plugin).
+- [Signal](/channels/signal) — signal-cli; privacy-focused.
+- [Slack](/channels/slack) — Bolt SDK; workspace apps.
+- [Synology Chat](/channels/synology-chat) — Synology NAS Chat via outgoing+incoming webhooks (bundled plugin).
+- [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
+- [Tlon](/channels/tlon) — Urbit-based messenger (bundled plugin).
+- [Twitch](/channels/twitch) — Twitch chat via IRC connection (bundled plugin).
+- [Voice Call](/plugins/voice-call) — Telephony via Plivo or Twilio (plugin, installed separately).
+- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
+- [WeChat](/channels/wechat) — Tencent iLink Bot plugin via QR login; private chats only (external plugin).
+- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
+- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (bundled plugin).
+- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (bundled plugin).
+
+## Notes
+
+- Channels can run simultaneously; configure multiple and OpenClaw will route per chat.
+- Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and
+  stores more state on disk.
+- Group behavior varies by channel; see [Groups](/channels/groups).
+- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
+- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).
+- Model providers are documented separately; see [Model Providers](/providers/models).
--- a/openclaw/docs/channels/irc.md
+++ b/openclaw/docs/channels/irc.md
@ -0,0 +1,252 @@
+---
+title: IRC
+summary: "IRC plugin setup, access controls, and troubleshooting"
+read_when:
+  - You want to connect OpenClaw to IRC channels or DMs
+  - You are configuring IRC allowlists, group policy, or mention gating
+---
+
+# IRC
+
+Use IRC when you want OpenClaw in classic channels (`#room`) and direct messages.
+IRC ships as an extension plugin, but it is configured in the main config under `channels.irc`.
+
+## Quick start
+
+1. Enable IRC config in `~/.openclaw/openclaw.json`.
+2. Set at least:
+
+```json5
+{
+  channels: {
+    irc: {
+      enabled: true,
+      host: "irc.example.com",
+      port: 6697,
+      tls: true,
+      nick: "openclaw-bot",
+      channels: ["#openclaw"],
+    },
+  },
+}
+```
+
+Prefer a private IRC server for bot coordination. If you intentionally use a public IRC network, common choices include Libera.Chat, OFTC, and Snoonet. Avoid predictable public channels for bot or swarm backchannel traffic.
+
+3. Start/restart gateway:
+
+```bash
+openclaw gateway run
+```
+
+## Security defaults
+
+- `channels.irc.dmPolicy` defaults to `"pairing"`.
+- `channels.irc.groupPolicy` defaults to `"allowlist"`.
+- With `groupPolicy="allowlist"`, set `channels.irc.groups` to define allowed channels.
+- Use TLS (`channels.irc.tls=true`) unless you intentionally accept plaintext transport.
+
+## Access control
+
+There are two separate “gates” for IRC channels:
+
+1. **Channel access** (`groupPolicy` + `groups`): whether the bot accepts messages from a channel at all.
+2. **Sender access** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): who is allowed to trigger the bot inside that channel.
+
+Config keys:
+
+- DM allowlist (DM sender access): `channels.irc.allowFrom`
+- Group sender allowlist (channel sender access): `channels.irc.groupAllowFrom`
+- Per-channel controls (channel + sender + mention rules): `channels.irc.groups["#channel"]`
+- `channels.irc.groupPolicy="open"` allows unconfigured channels (**still mention-gated by default**)
+
+Allowlist entries should use stable sender identities (`nick!user@host`).
+Bare nick matching is mutable and only enabled when `channels.irc.dangerouslyAllowNameMatching: true`.
+
+### Common gotcha: `allowFrom` is for DMs, not channels
+
+If you see logs like:
+
+- `irc: drop group sender alice!ident@host (policy=allowlist)`
+
+…it means the sender wasn’t allowed for **group/channel** messages. Fix it by either:
+
+- setting `channels.irc.groupAllowFrom` (global for all channels), or
+- setting per-channel sender allowlists: `channels.irc.groups["#channel"].allowFrom`
+
+Example (allow anyone in `#tuirc-dev` to talk to the bot):
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": { allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Reply triggering (mentions)
+
+Even if a channel is allowed (via `groupPolicy` + `groups`) and the sender is allowed, OpenClaw defaults to **mention-gating** in group contexts.
+
+That means you may see logs like `drop channel … (missing-mention)` unless the message includes a mention pattern that matches the bot.
+
+To make the bot reply in an IRC channel **without needing a mention**, disable mention gating for that channel:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": {
+          requireMention: false,
+          allowFrom: ["*"],
+        },
+      },
+    },
+  },
+}
+```
+
+Or to allow **all** IRC channels (no per-channel allowlist) and still reply without mentions:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "open",
+      groups: {
+        "*": { requireMention: false, allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Security note (recommended for public channels)
+
+If you allow `allowFrom: ["*"]` in a public channel, anyone can prompt the bot.
+To reduce risk, restrict tools for that channel.
+
+### Same tools for everyone in the channel
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          tools: {
+            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Different tools per sender (owner gets more power)
+
+Use `toolsBySender` to apply a stricter policy to `"*"` and a looser one to your nick:
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          toolsBySender: {
+            "*": {
+              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+            },
+            "id:eigen": {
+              deny: ["gateway", "nodes", "cron"],
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- `toolsBySender` keys should use `id:` for IRC sender identity values:
+  `id:eigen` or `id:eigen!~eigen@174.127.248.171` for stronger matching.
+- Legacy unprefixed keys are still accepted and matched as `id:` only.
+- The first matching sender policy wins; `"*"` is the wildcard fallback.
+
+For more on group access vs mention-gating (and how they interact), see: [/channels/groups](/channels/groups).
+
+## NickServ
+
+To identify with NickServ after connect:
+
+```json5
+{
+  channels: {
+    irc: {
+      nickserv: {
+        enabled: true,
+        service: "NickServ",
+        password: "your-nickserv-password",
+      },
+    },
+  },
+}
+```
+
+Optional one-time registration on connect:
+
+```json5
+{
+  channels: {
+    irc: {
+      nickserv: {
+        register: true,
+        registerEmail: "bot@example.com",
+      },
+    },
+  },
+}
+```
+
+Disable `register` after the nick is registered to avoid repeated REGISTER attempts.
+
+## Environment variables
+
+Default account supports:
+
+- `IRC_HOST`
+- `IRC_PORT`
+- `IRC_TLS`
+- `IRC_NICK`
+- `IRC_USERNAME`
+- `IRC_REALNAME`
+- `IRC_PASSWORD`
+- `IRC_CHANNELS` (comma-separated)
+- `IRC_NICKSERV_PASSWORD`
+- `IRC_NICKSERV_REGISTER_EMAIL`
+
+## Troubleshooting
+
+- If the bot connects but never replies in channels, verify `channels.irc.groups` **and** whether mention-gating is dropping messages (`missing-mention`). If you want it to reply without pings, set `requireMention:false` for the channel.
+- If login fails, verify nick availability and server password.
+- If TLS fails on a custom network, verify host/port and certificate setup.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/openclaw/docs/channels/line.md
+++ b/openclaw/docs/channels/line.md
@ -0,0 +1,225 @@
+---
+summary: "LINE Messaging API plugin setup, config, and usage"
+read_when:
+  - You want to connect OpenClaw to LINE
+  - You need LINE webhook + credential setup
+  - You want LINE-specific message options
+title: LINE
+---
+
+# LINE
+
+LINE connects to OpenClaw via the LINE Messaging API. The plugin runs as a webhook
+receiver on the gateway and uses your channel access token + channel secret for
+authentication.
+
+Status: bundled plugin. Direct messages, group chats, media, locations, Flex
+messages, template messages, and quick replies are supported. Reactions and threads
+are not supported.
+
+## Bundled plugin
+
+LINE ships as a bundled plugin in current OpenClaw releases, so normal
+packaged builds do not need a separate install.
+
+If you are on an older build or a custom install that excludes LINE, install it
+manually:
+
+```bash
+openclaw plugins install @openclaw/line
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+openclaw plugins install ./path/to/local/line-plugin
+```
+
+## Setup
+
+1. Create a LINE Developers account and open the Console:
+   [https://developers.line.biz/console/](https://developers.line.biz/console/)
+2. Create (or pick) a Provider and add a **Messaging API** channel.
+3. Copy the **Channel access token** and **Channel secret** from the channel settings.
+4. Enable **Use webhook** in the Messaging API settings.
+5. Set the webhook URL to your gateway endpoint (HTTPS required):
+
+```
+https://gateway-host/line/webhook
+```
+
+The gateway responds to LINE’s webhook verification (GET) and inbound events (POST).
+If you need a custom path, set `channels.line.webhookPath` or
+`channels.line.accounts.<id>.webhookPath` and update the URL accordingly.
+
+Security note:
+
+- LINE signature verification is body-dependent (HMAC over the raw body), so OpenClaw applies strict pre-auth body limits and timeout before verification.
+- OpenClaw processes webhook events from the verified raw request bytes. Upstream middleware-transformed `req.body` values are ignored for signature-integrity safety.
+
+## Configure
+
+Minimal config:
+
+```json5
+{
+  channels: {
+    line: {
+      enabled: true,
+      channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
+      channelSecret: "LINE_CHANNEL_SECRET",
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+Env vars (default account only):
+
+- `LINE_CHANNEL_ACCESS_TOKEN`
+- `LINE_CHANNEL_SECRET`
+
+Token/secret files:
+
+```json5
+{
+  channels: {
+    line: {
+      tokenFile: "/path/to/line-token.txt",
+      secretFile: "/path/to/line-secret.txt",
+    },
+  },
+}
+```
+
+`tokenFile` and `secretFile` must point to regular files. Symlinks are rejected.
+
+Multiple accounts:
+
+```json5
+{
+  channels: {
+    line: {
+      accounts: {
+        marketing: {
+          channelAccessToken: "...",
+          channelSecret: "...",
+          webhookPath: "/line/marketing",
+        },
+      },
+    },
+  },
+}
+```
+
+## Access control
+
+Direct messages default to pairing. Unknown senders get a pairing code and their
+messages are ignored until approved.
+
+```bash
+openclaw pairing list line
+openclaw pairing approve line <CODE>
+```
+
+Allowlists and policies:
+
+- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
+- `channels.line.allowFrom`: allowlisted LINE user IDs for DMs
+- `channels.line.groupPolicy`: `allowlist | open | disabled`
+- `channels.line.groupAllowFrom`: allowlisted LINE user IDs for groups
+- Per-group overrides: `channels.line.groups.<groupId>.allowFrom`
+- Runtime note: if `channels.line` is completely missing, runtime falls back to `groupPolicy="allowlist"` for group checks (even if `channels.defaults.groupPolicy` is set).
+
+LINE IDs are case-sensitive. Valid IDs look like:
+
+- User: `U` + 32 hex chars
+- Group: `C` + 32 hex chars
+- Room: `R` + 32 hex chars
+
+## Message behavior
+
+- Text is chunked at 5000 characters.
+- Markdown formatting is stripped; code blocks and tables are converted into Flex
+  cards when possible.
+- Streaming responses are buffered; LINE receives full chunks with a loading
+  animation while the agent works.
+- Media downloads are capped by `channels.line.mediaMaxMb` (default 10).
+
+## Channel data (rich messages)
+
+Use `channelData.line` to send quick replies, locations, Flex cards, or template
+messages.
+
+```json5
+{
+  text: "Here you go",
+  channelData: {
+    line: {
+      quickReplies: ["Status", "Help"],
+      location: {
+        title: "Office",
+        address: "123 Main St",
+        latitude: 35.681236,
+        longitude: 139.767125,
+      },
+      flexMessage: {
+        altText: "Status card",
+        contents: {
+          /* Flex payload */
+        },
+      },
+      templateMessage: {
+        type: "confirm",
+        text: "Proceed?",
+        confirmLabel: "Yes",
+        confirmData: "yes",
+        cancelLabel: "No",
+        cancelData: "no",
+      },
+    },
+  },
+}
+```
+
+The LINE plugin also ships a `/card` command for Flex message presets:
+
+```
+/card info "Welcome" "Thanks for joining!"
+```
+
+## ACP support
+
+LINE supports ACP (Agent Communication Protocol) conversation bindings:
+
+- `/acp spawn <agent> --bind here` binds the current LINE chat to an ACP session without creating a child thread.
+- Configured ACP bindings and active conversation-bound ACP sessions work on LINE like other conversation channels.
+
+See [ACP agents](/tools/acp-agents) for details.
+
+## Outbound media
+
+The LINE plugin supports sending images, videos, and audio files through the agent message tool. Media is sent via the LINE-specific delivery path with appropriate preview and tracking handling:
+
+- **Images**: sent as LINE image messages with automatic preview generation.
+- **Videos**: sent with explicit preview and content-type handling.
+- **Audio**: sent as LINE audio messages.
+
+Generic media sends fall back to the existing image-only route when a LINE-specific path is not available.
+
+## Troubleshooting
+
+- **Webhook verification fails:** ensure the webhook URL is HTTPS and the
+  `channelSecret` matches the LINE console.
+- **No inbound events:** confirm the webhook path matches `channels.line.webhookPath`
+  and that the gateway is reachable from LINE.
+- **Media download errors:** raise `channels.line.mediaMaxMb` if media exceeds the
+  default limit.
+
+## Related
+
+- [Channels Overview](/channels) — all supported channels
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Security](/gateway/security) — access model and hardening
--- a/Show more
+++ b/Show more