Gateway: fix multi-agent sessions.usage discovery (#11523)

* Gateway: fix multi-agent sessions.usage discovery

* Gateway: resolve sessions.usage keys via sessionId

.agents/skills/PR_WORKFLOW.md

@@ -0,0 +1,125 @@
+# PR Review Instructions
+
+Please read this in full and do not skip sections.
+
+## Working rule
+
+Skills execute workflow, maintainers provide judgment.
+Always pause between skills to evaluate technical direction, not just command success.
+
+These three skills must be used in order:
+
+1. `review-pr`
+2. `prepare-pr`
+3. `merge-pr`
+
+They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward.
+
+Treat PRs as reports first, code second.
+If submitted code is low quality, ignore it and implement the best solution for the problem.
+
+Do not continue if you cannot verify the problem is real or test the fix.
+
+## PR quality bar
+
+- Do not trust PR code by default.
+- Do not merge changes you cannot validate with a reproducible problem and a tested fix.
+- Keep types strict. Do not use `any` in implementation code.
+- Keep external-input boundaries typed and validated, including CLI input, environment variables, network payloads, and tool output.
+- Keep implementations properly scoped. Fix root causes, not local symptoms.
+- Identify and reuse canonical sources of truth so behavior does not drift across the codebase.
+- Harden changes. Always evaluate security impact and abuse paths.
+- Understand the system before changing it. Never make the codebase messier just to clear a PR queue.
+
+## Unified workflow
+
+Entry criteria:
+
+- PR URL/number is known.
+- Problem statement is clear enough to attempt reproduction.
+- A realistic verification path exists (tests, integration checks, or explicit manual validation).
+
+### 1) `review-pr`
+
+Purpose:
+
+- Review only: correctness, value, security risk, tests, docs, and changelog impact.
+- Produce structured findings and a recommendation.
+
+Expected output:
+
+- Recommendation: ready, needs work, needs discussion, or close.
+- `.local/review.md` with actionable findings.
+
+Maintainer checkpoint before `prepare-pr`:
+
+```
+What problem are they trying to solve?
+What is the most optimal implementation?
+Is the code properly scoped?
+Can we fix up everything?
+Do we have any questions?
+```
+
+Stop and escalate instead of continuing if:
+
+- The problem cannot be reproduced or confirmed.
+- The proposed PR scope does not match the stated problem.
+- The design introduces unresolved security or trust-boundary concerns.
+
+### 2) `prepare-pr`
+
+Purpose:
+
+- Make the PR merge-ready on its head branch.
+- Rebase onto current `main`, fix blocker/important findings, and run gates.
+
+Expected output:
+
+- Updated code and tests on the PR head branch.
+- `.local/prep.md` with changes, verification, and current HEAD SHA.
+- Final status: `PR is ready for /mergepr`.
+
+Maintainer checkpoint before `merge-pr`:
+
+```
+Is this the most optimal implementation?
+Is the code properly scoped?
+Is the code properly typed?
+Is the code hardened?
+Do we have enough tests?
+Do not add performative tests, ensure tests are real and there are no regressions.
+Take your time, fix it properly, refactor if necessary.
+Do you see any follow-up refactors we should do?
+Did any changes introduce any potential security vulnerabilities?
+```
+
+Stop and escalate instead of continuing if:
+
+- You cannot verify behavior changes with meaningful tests or validation.
+- Fixing findings requires broad architecture changes outside safe PR scope.
+- Security hardening requirements remain unresolved.
+
+### 3) `merge-pr`
+
+Purpose:
+
+- Merge only after review and prep artifacts are present and checks are green.
+- Use squash merge flow and verify the PR ends in `MERGED` state.
+
+Go or no-go checklist before merge:
+
+- All BLOCKER and IMPORTANT findings are resolved.
+- Verification is meaningful and regression risk is acceptably low.
+- Docs and changelog are updated when required.
+- Required CI checks are green and the branch is not behind `main`.
+
+Expected output:
+
+- Successful merge commit and recorded merge SHA.
+- Worktree cleanup after successful merge.
+
+Maintainer checkpoint after merge:
+
+- Were any refactors intentionally deferred and now need follow-up issue(s)?
+- Did this reveal broader architecture or test gaps we should address?

.agents/skills/merge-pr/SKILL.md

@@ -28,7 +28,7 @@ Merge a prepared PR via `gh pr merge --squash` and clean up the worktree after s
 
 ## Known Footguns
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/Development/openclaw`, not `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Read `.local/review.md` and `.local/prep.md` in the worktree. Do not skip.
 - Clean up the real worktree directory `.worktrees/pr-<PR>` only after a successful merge.
 - Expect cleanup to remove `.local/` artifacts.

.agents/skills/prepare-pr/SKILL.md

@@ -30,7 +30,7 @@ Prepare a PR branch for merge with review fixes, green gates, and an updated hea
 
 ## Known Footguns
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Do not run `git clean -fdx`.
 - Do not run `git add -A` or `git add .`.
 

.agents/skills/review-pr/SKILL.md

@@ -28,7 +28,7 @@ Perform a thorough review-only PR assessment and return a structured recommendat
 
 ## Known Failure Modes
 
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/openclaw`.
+- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
 - Do not stop after printing the checklist. That is not completion.
 
 ## Writing Style for Output

.github/actions/detect-docs-only/action.yml

@@ -0,0 +1,41 @@
+name: Detect docs-only changes
+description: >
+  Outputs docs_only=true when all changed files are under docs/ or are
+  markdown (.md/.mdx). Fail-safe: if detection fails, outputs false (run
+  everything). Uses git diff — no API calls, no extra permissions needed.
+
+outputs:
+  docs_only:
+    description: "'true' if all changes are docs/markdown, 'false' otherwise"
+    value: ${{ steps.check.outputs.docs_only }}
+
+runs:
+  using: composite
+  steps:
+    - name: Detect docs-only changes
+      id: check
+      shell: bash
+      run: |
+        if [ "${{ github.event_name }}" = "push" ]; then
+          BASE="${{ github.event.before }}"
+        else
+          # Use the exact base SHA from the event payload — stable regardless
+          # of base branch movement (avoids origin/<ref> drift).
+          BASE="${{ github.event.pull_request.base.sha }}"
+        fi
+
+        # Fail-safe: if we can't diff, assume non-docs (run everything)
+        CHANGED=$(git diff --name-only "$BASE" HEAD 2>/dev/null || echo "UNKNOWN")
+        if [ "$CHANGED" = "UNKNOWN" ] || [ -z "$CHANGED" ]; then
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Check if all changed files are docs or markdown
+        NON_DOCS=$(echo "$CHANGED" | grep -vE '^docs/|\.md$|\.mdx$' || true)
+        if [ -z "$NON_DOCS" ]; then
+          echo "docs_only=true" >> "$GITHUB_OUTPUT"
+          echo "Docs-only change detected — skipping heavy jobs"
+        else
+          echo "docs_only=false" >> "$GITHUB_OUTPUT"
+        fi

.github/workflows/ci.yml

@@ -10,7 +10,26 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Detect docs-only changes to skip heavy jobs (test, build, Windows, macOS, Android).
+  # Lint and format always run. Fail-safe: if detection fails, run everything.
+  docs-scope:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.check.outputs.docs_only }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: false
+
+      - name: Detect docs-only changes
+        id: check
+        uses: ./.github/actions/detect-docs-only
+
   install-check:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
@@ -71,6 +90,8 @@ jobs:
           pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
   checks:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false
@@ -79,18 +100,12 @@ jobs:
           - runtime: node
             task: tsgo
             command: pnpm tsgo
-          - runtime: node
-            task: lint
-            command: pnpm build && pnpm lint
           - runtime: node
             task: test
             command: pnpm canvas:a2ui:bundle && pnpm test
           - runtime: node
             task: protocol
             command: pnpm protocol:check
-          - runtime: node
-            task: format
-            command: pnpm format
           - runtime: bun
             task: test
             command: pnpm canvas:a2ui:bundle && bunx vitest run
@@ -161,6 +176,84 @@ jobs:
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
+  # Lint and format always run, even on docs-only changes.
+  checks-lint:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: lint
+            command: pnpm build && pnpm lint
+          - task: format
+            command: pnpm format
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }}
+        run: ${{ matrix.command }}
+
   secrets:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
@@ -187,6 +280,8 @@ jobs:
           fi
 
   checks-windows:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-windows-2025
     env:
       NODE_OPTIONS: --max-old-space-size=4096
@@ -300,7 +395,8 @@ jobs:
   # running 4 separate jobs per PR (as before) starved the queue. One job
   # per PR allows 5 PRs to run macOS checks simultaneously.
   macos:
-    if: github.event_name == 'pull_request'
+    needs: [docs-scope]
+    if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true'
     runs-on: macos-latest
     steps:
       - name: Checkout
@@ -585,6 +681,8 @@ jobs:
           PY
 
   android:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
       fail-fast: false

.github/workflows/install-smoke.yml

@@ -11,7 +11,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  docs-scope:
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.check.outputs.docs_only }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Detect docs-only changes
+        id: check
+        uses: ./.github/actions/detect-docs-only
+
   install-smoke:
+    needs: [docs-scope]
+    if: needs.docs-scope.outputs.docs_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout CLI

CHANGELOG.md

@@ -29,6 +29,7 @@ Docs: https://docs.openclaw.ai
 - Cron: scheduler reliability (timer drift, restart catch-up, lock contention, stale running markers). (#10776) Thanks @tyler6204.
 - Cron: store migration hardening (legacy field migration, parse error handling, explicit delivery mode persistence). (#10776) Thanks @tyler6204.
 - Memory: set Voyage embeddings `input_type` for improved retrieval. (#10818) Thanks @mcinteerj.
+- Media understanding: recognize `.caf` audio attachments for transcription. (#10982) Thanks @succ985.
 - Telegram: auto-inject DM topic threadId in message tool + subagent announce. (#7235) Thanks @Lukavyi.
 - Security: require auth for Gateway canvas host and A2UI assets. (#9518) Thanks @coygeek.
 - Cron: fix scheduling and reminder delivery regressions; harden next-run recompute + timer re-arming + legacy schedule fields. (#9733, #9823, #9948, #9932) Thanks @tyler6204, @pycckuu, @j2h4u, @fujiwara-tofu-shop.

docs/automation/hooks.md

@@ -17,7 +17,7 @@ Hooks are small scripts that run when something happens. There are two kinds:
 - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
 - **Webhooks**: external HTTP webhooks that let other systems trigger work in OpenClaw. See [Webhook Hooks](/automation/webhook) or use `openclaw webhooks` for Gmail helper commands.
 
-Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks).
+Hooks can also be bundled inside plugins; see [Plugins](/tools/plugin#plugin-hooks).
 
 Common uses:
 

docs/channels/bluebubbles.md

@@ -18,7 +18,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 - 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 (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
+- 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.
 
@@ -149,7 +149,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list bluebubbles`
   - `openclaw pairing approve bluebubbles <CODE>`
-- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
 
 Groups:
 
@@ -337,4 +337,4 @@ Prefer `chat_guid` for stable routing:
 - 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](/plugin) guide.
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/tools/plugin) guide.

docs/channels/broadcast-groups.md

@@ -437,6 +437,6 @@ Planned features:
 
 ## See Also
 
-- [Multi-Agent Configuration](/multi-agent-sandbox-tools)
+- [Multi-Agent Configuration](/tools/multi-agent-sandbox-tools)
-- [Routing Configuration](/concepts/channel-routing)
+- [Routing Configuration](/channels/channel-routing)
 - [Session Management](/concepts/sessions)

docs/channels/channel-routing.md

@@ -68,7 +68,7 @@ Config:
 }
 ```
 
-See: [Broadcast Groups](/broadcast-groups).
+See: [Broadcast Groups](/channels/broadcast-groups).
 
 ## Config overview
 

docs/channels/groups.md

@@ -371,4 +371,4 @@ The agent system prompt includes a group intro on the first turn of a new group
 
 ## WhatsApp specifics
 
-See [Group messages](/concepts/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
+See [Group messages](/channels/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

docs/channels/imessage.md

@@ -224,7 +224,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list imessage`
   - `openclaw pairing approve imessage <CODE>`
-- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/channels/pairing)
 
 Groups:
 

docs/channels/index.md

@@ -39,7 +39,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - 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](/concepts/groups).
+- Group behavior varies by channel; see [Groups](/channels/groups).
 - DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
 - Telegram internals: [grammY notes](/channels/grammy).
 - Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).

docs/channels/matrix.md

@@ -34,7 +34,7 @@ openclaw plugins install ./extensions/matrix
 If you choose Matrix during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Setup
 

docs/channels/mattermost.md

@@ -31,7 +31,7 @@ openclaw plugins install ./extensions/mattermost
 If you choose Mattermost during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup
 

docs/channels/msteams.md

@@ -36,7 +36,7 @@ openclaw plugins install ./extensions/msteams
 If you choose Teams during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/nextcloud-talk.md

@@ -28,7 +28,7 @@ openclaw plugins install ./extensions/nextcloud-talk
 If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected,
 OpenClaw will offer the local install path automatically.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/signal.md

@@ -109,7 +109,7 @@ DMs:
 - Approve via:
   - `openclaw pairing list signal`
   - `openclaw pairing approve signal <CODE>`
-- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/channels/pairing)
 - UUID-only senders (from `sourceUuid`) are stored as `uuid:<id>` in `channels.signal.allowFrom`.
 
 Groups:

docs/channels/telegram.md

@@ -351,7 +351,7 @@ Use the global setting when all Telegram bots/accounts should behave the same. U
 - Approve via:
   - `openclaw pairing list telegram`
   - `openclaw pairing approve telegram <CODE>`
-- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/channels/pairing)
 - `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID. The wizard accepts `@username` and resolves it to the numeric ID when possible.
 
 #### Finding your Telegram user ID

docs/channels/tlon.md

@@ -30,7 +30,7 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./extensions/tlon
 ```
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Setup
 

docs/channels/twitch.md

@@ -25,7 +25,7 @@ Local checkout (when running from a git repo):
 openclaw plugins install ./extensions/twitch
 ```
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 

docs/channels/zalo.md

@@ -15,7 +15,7 @@ Zalo ships as a plugin and is not bundled with the core install.
 
 - Install via CLI: `openclaw plugins install @openclaw/zalo`
 - Or select **Zalo** during onboarding and confirm the install prompt
-- Details: [Plugins](/plugin)
+- Details: [Plugins](/tools/plugin)
 
 ## Quick setup (beginner)
 
@@ -104,7 +104,7 @@ Multi-account support: use `channels.zalo.accounts` with per-account tokens and
 - Approve via:
   - `openclaw pairing list zalo`
   - `openclaw pairing approve zalo <CODE>`
-- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- Pairing is the default token exchange. Details: [Pairing](/channels/pairing)
 - `channels.zalo.allowFrom` accepts numeric user IDs (no username lookup available).
 
 ## Long-polling vs webhook

docs/channels/zalouser.md

@@ -18,7 +18,7 @@ Zalo Personal ships as a plugin and is not bundled with the core install.
 
 - Install via CLI: `openclaw plugins install @openclaw/zalouser`
 - Or from a source checkout: `openclaw plugins install ./extensions/zalouser`
-- Details: [Plugins](/plugin)
+- Details: [Plugins](/tools/plugin)
 
 ## Prerequisite: zca-cli
 

docs/cli/hooks.md

@@ -12,8 +12,8 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`,
 
 Related:
 
-- Hooks: [Hooks](/hooks)
+- Hooks: [Hooks](/automation/hooks)
-- Plugin hooks: [Plugins](/plugin#plugin-hooks)
+- Plugin hooks: [Plugins](/tools/plugin#plugin-hooks)
 
 ## List All Hooks
 
@@ -248,7 +248,7 @@ openclaw hooks enable session-memory
 
 **Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
 
-**See:** [session-memory documentation](/hooks#session-memory)
+**See:** [session-memory documentation](/automation/hooks#session-memory)
 
 ### command-logger
 
@@ -275,7 +275,7 @@ cat ~/.openclaw/logs/commands.log | jq .
 grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 ```
 
-**See:** [command-logger documentation](/hooks#command-logger)
+**See:** [command-logger documentation](/automation/hooks#command-logger)
 
 ### soul-evil
 
@@ -301,4 +301,4 @@ Runs `BOOT.md` when the gateway starts (after channels start).
 openclaw hooks enable boot-md
 ```
 
-**See:** [boot-md documentation](/hooks#boot-md)
+**See:** [boot-md documentation](/automation/hooks#boot-md)

docs/cli/index.md

@@ -255,7 +255,7 @@ Manage extensions and their config:
 - `openclaw plugins enable <id>` / `disable <id>` — toggle `plugins.entries.<id>.enabled`.
 - `openclaw plugins doctor` — report plugin load errors.
 
-Most plugin changes require a gateway restart. See [/plugin](/plugin).
+Most plugin changes require a gateway restart. See [/plugin](/tools/plugin).
 
 ## Memory
 

docs/cli/memory.md

@@ -14,7 +14,7 @@ Provided by the active memory plugin (default: `memory-core`; set `plugins.slots
 Related:
 
 - Memory concept: [Memory](/concepts/memory)
-- Plugins: [Plugins](/plugin)
+- Plugins: [Plugins](/tools/plugin)
 
 ## Examples
 

docs/cli/pairing.md

@@ -11,7 +11,7 @@ Approve or inspect DM pairing requests (for channels that support pairing).
 
 Related:
 
-- Pairing flow: [Pairing](/start/pairing)
+- Pairing flow: [Pairing](/channels/pairing)
 
 ## Commands
 

docs/cli/plugins.md

@@ -12,7 +12,7 @@ Manage Gateway plugins/extensions (loaded in-process).
 
 Related:
 
-- Plugin system: [Plugins](/plugin)
+- Plugin system: [Plugins](/tools/plugin)
 - Plugin manifest + schema: [Plugin manifest](/plugins/manifest)
 - Security hardening: [Security](/gateway/security)
 

docs/cli/tui.md

@@ -12,7 +12,7 @@ Open the terminal UI connected to the Gateway.
 
 Related:
 
-- TUI guide: [TUI](/tui)
+- TUI guide: [TUI](/web/tui)
 
 ## Examples
 

docs/concepts/agent-loop.md

@@ -75,7 +75,7 @@ OpenClaw has two hook systems:
   Use this to add/remove bootstrap context files.
 - **Command hooks**: `/new`, `/reset`, `/stop`, and other command events (see Hooks doc).
 
-See [Hooks](/hooks) for setup and examples.
+See [Hooks](/automation/hooks) for setup and examples.
 
 ### Plugin hooks (agent + gateway lifecycle)
 
@@ -90,7 +90,7 @@ These run inside the agent loop or gateway pipeline:
 - **`session_start` / `session_end`**: session lifecycle boundaries.
 - **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
 
-See [Plugins](/plugin#plugin-hooks) for the hook API and registration details.
+See [Plugins](/tools/plugin#plugin-hooks) for the hook API and registration details.
 
 ## Streaming + partial replies
 

docs/concepts/agent-workspace.md

@@ -228,6 +228,6 @@ Suggested `.gitignore` starter:
 ## Advanced notes
 
 - Multi-agent routing can use different workspaces per agent. See
-  [Channel routing](/concepts/channel-routing) for routing configuration.
+  [Channel routing](/channels/channel-routing) for routing configuration.
 - If `agents.defaults.sandbox` is enabled, non-main sessions can use per-session sandbox
   workspaces under `agents.defaults.sandbox.workspaceRoot`.

docs/concepts/agent.md

@@ -120,4 +120,4 @@ At minimum, set:
 
 ---
 
-_Next: [Group Chats](/concepts/group-messages)_ 🦞
+_Next: [Group Chats](/channels/group-messages)_ 🦞

docs/concepts/architecture.md

@@ -97,7 +97,7 @@ Client                    Gateway
 - Gateway auth (`gateway.auth.*`) still applies to **all** connections, local or
   remote.
 
-Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing),
+Details: [Gateway protocol](/gateway/protocol), [Pairing](/channels/pairing),
 [Security](/gateway/security).
 
 ## Protocol typing and codegen

docs/concepts/context.md

@@ -27,7 +27,7 @@ Context is _not the same thing_ as “memory”: memory can be stored on disk an
 - `/usage tokens` → append per-reply usage footer to normal replies.
 - `/compact` → summarize older history into a compact entry to free window space.
 
-See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction).
+See also: [Slash commands](/tools/slash-commands), [Token use & costs](/reference/token-use), [Compaction](/concepts/compaction).
 
 ## Example output
 

docs/concepts/messages.md

@@ -142,7 +142,7 @@ OpenClaw can expose or hide model reasoning:
 - Reasoning content still counts toward token usage when produced by the model.
 - Telegram supports reasoning stream into the draft bubble.
 
-Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/token-use).
+Details: [Thinking + reasoning directives](/tools/thinking) and [Token use](/reference/token-use).
 
 ## Prefixes, threading, and replies
 

docs/concepts/models.md

@@ -194,7 +194,7 @@ Scan results are ranked by:
 Input
 
 - OpenRouter `/models` list (filter `:free`)
-- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/environment))
+- Requires OpenRouter API key from auth profiles or `OPENROUTER_API_KEY` (see [/environment](/help/environment))
 - Optional filters: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
 - Probe controls: `--timeout`, `--concurrency`
 

docs/concepts/multi-agent.md

@@ -112,7 +112,7 @@ Example:
 Notes:
 
 - DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
-- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).
+- For shared groups, bind the group to one agent or use [Broadcast groups](/channels/broadcast-groups).
 
 ## Routing rules (how messages pick an agent)
 
@@ -373,4 +373,4 @@ Note: `tools.elevated` is **global** and sender-based; it is not configurable pe
 If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
 For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for detailed examples.

docs/docs.json

@@ -38,18 +38,6 @@
     ]
   },
   "redirects": [
-    {
-      "source": "/cron",
-      "destination": "/cron-jobs"
-    },
-    {
-      "source": "/model",
-      "destination": "/models"
-    },
-    {
-      "source": "/model/",
-      "destination": "/models"
-    },
     {
       "source": "/messages",
       "destination": "/concepts/messages"
@@ -62,6 +50,10 @@
       "source": "/compaction",
       "destination": "/concepts/compaction"
     },
+    {
+      "source": "/cron",
+      "destination": "/cron-jobs"
+    },
     {
       "source": "/minimax",
       "destination": "/providers/minimax"
@@ -356,11 +348,11 @@
     },
     {
       "source": "/group-messages",
-      "destination": "/concepts/group-messages"
+      "destination": "/channels/group-messages"
     },
     {
       "source": "/groups",
-      "destination": "/concepts/groups"
+      "destination": "/channels/groups"
     },
     {
       "source": "/health",
@@ -486,6 +478,14 @@
       "source": "/model-failover",
       "destination": "/concepts/model-failover"
     },
+    {
+      "source": "/model",
+      "destination": "/models"
+    },
+    {
+      "source": "/model/",
+      "destination": "/models"
+    },
     {
       "source": "/models",
       "destination": "/concepts/models"
@@ -508,7 +508,7 @@
     },
     {
       "source": "/pairing",
-      "destination": "/start/pairing"
+      "destination": "/channels/pairing"
     },
     {
       "source": "/plans/cron-add-hardening",
@@ -532,11 +532,11 @@
     },
     {
       "source": "/provider-routing",
-      "destination": "/concepts/channel-routing"
+      "destination": "/channels/channel-routing"
     },
     {
       "source": "/concepts/provider-routing",
-      "destination": "/concepts/channel-routing"
+      "destination": "/channels/channel-routing"
     },
     {
       "source": "/queue",
@@ -667,8 +667,8 @@
       "destination": "/help/troubleshooting"
     },
     {
-      "source": "/web/tui",
+      "source": "/tui",
-      "destination": "/tui"
+      "destination": "/web/tui"
     },
     {
       "source": "/typebox",
@@ -722,9 +722,13 @@
       "source": "/oauth",
       "destination": "/concepts/oauth"
     },
+    {
+      "source": "/plugin",
+      "destination": "/tools/plugin"
+    },
     {
       "source": "/plugins",
-      "destination": "/plugin"
+      "destination": "/tools/plugin"
     },
     {
       "source": "/railway",
@@ -783,9 +787,17 @@
           {
             "tab": "Get started",
             "groups": [
+              {
+                "group": "Home",
+                "pages": ["index"]
+              },
               {
                 "group": "Overview",
-                "pages": ["index", "concepts/features", "start/showcase"]
+                "pages": ["start/showcase"]
+              },
+              {
+                "group": "Core concepts",
+                "pages": ["concepts/features"]
               },
               {
                 "group": "First steps",
@@ -861,11 +873,11 @@
               {
                 "group": "Configuration",
                 "pages": [
-                  "start/pairing",
+                  "channels/pairing",
-                  "concepts/group-messages",
+                  "channels/group-messages",
-                  "concepts/groups",
+                  "channels/groups",
-                  "broadcast-groups",
+                  "channels/broadcast-groups",
-                  "concepts/channel-routing",
+                  "channels/channel-routing",
                   "channels/location",
                   "channels/troubleshooting"
                 ]
@@ -884,10 +896,13 @@
                   "concepts/system-prompt",
                   "concepts/context",
                   "concepts/agent-workspace",
-                  "start/bootstrapping",
                   "concepts/oauth"
                 ]
               },
+              {
+                "group": "Bootstrapping",
+                "pages": ["start/bootstrapping"]
+              },
               {
                 "group": "Sessions and memory",
                 "pages": [
@@ -945,25 +960,26 @@
               },
               {
                 "group": "Agent coordination",
-                "pages": ["tools/agent-send", "tools/subagents", "multi-agent-sandbox-tools"]
+                "pages": ["tools/agent-send", "tools/subagents", "tools/multi-agent-sandbox-tools"]
               },
               {
-                "group": "Skills and extensions",
+                "group": "Skills",
                 "pages": [
                   "tools/slash-commands",
                   "tools/skills",
                   "tools/skills-config",
                   "tools/clawhub",
-                  "plugin",
+                  "tools/plugin"
-                  "plugins/voice-call",
-                  "plugins/zalouser"
                 ]
               },
+              {
+                "group": "Extensions",
+                "pages": ["plugins/voice-call", "plugins/zalouser"]
+              },
               {
                 "group": "Automation",
                 "pages": [
-                  "hooks",
+                  "automation/hooks",
-                  "hooks/soul-evil",
                   "automation/cron-jobs",
                   "automation/cron-vs-heartbeat",
                   "automation/troubleshooting",
@@ -973,6 +989,10 @@
                   "automation/auth-monitoring"
                 ]
               },
+              {
+                "group": "Hooks",
+                "pages": ["hooks/soul-evil"]
+              },
               {
                 "group": "Media and devices",
                 "pages": [
@@ -993,7 +1013,11 @@
             "groups": [
               {
                 "group": "Overview",
-                "pages": ["providers/index", "providers/models", "concepts/models"]
+                "pages": ["providers/index", "providers/models"]
+              },
+              {
+                "group": "Model concepts",
+                "pages": ["concepts/models"]
               },
               {
                 "group": "Configuration",
@@ -1005,7 +1029,7 @@
                   "providers/anthropic",
                   "providers/openai",
                   "providers/openrouter",
-                  "bedrock",
+                  "providers/bedrock",
                   "providers/vercel-ai-gateway",
                   "providers/moonshot",
                   "providers/minimax",
@@ -1120,7 +1144,7 @@
               },
               {
                 "group": "Web interfaces",
-                "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "tui"]
+                "pages": ["web/index", "web/control-ui", "web/dashboard", "web/webchat", "web/tui"]
               }
             ]
           },
@@ -1188,14 +1212,16 @@
               },
               {
                 "group": "Technical reference",
+                "pages": ["reference/wizard", "reference/token-use"]
+              },
+              {
+                "group": "Concept internals",
                 "pages": [
-                  "reference/wizard",
                   "concepts/typebox",
                   "concepts/markdown-formatting",
                   "concepts/typing-indicators",
                   "concepts/usage-tracking",
-                  "concepts/timezone",
+                  "concepts/timezone"
-                  "token-use"
                 ]
               },
               {
@@ -1221,18 +1247,23 @@
               },
               {
                 "group": "Environment and debugging",
-                "pages": [
+                "pages": ["help/environment", "help/debugging", "help/testing", "help/scripts"]
-                  "install/node",
-                  "environment",
-                  "debugging",
-                  "testing",
-                  "scripts",
-                  "reference/session-management-compaction"
-                ]
               },
               {
-                "group": "Developer workflows",
+                "group": "Node runtime",
-                "pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"]
+                "pages": ["install/node"]
+              },
+              {
+                "group": "Compaction internals",
+                "pages": ["reference/session-management-compaction"]
+              },
+              {
+                "group": "Developer setup",
+                "pages": ["start/setup"]
+              },
+              {
+                "group": "Contributing",
+                "pages": ["help/submitting-a-pr", "help/submitting-an-issue"]
               },
               {
                 "group": "Docs meta",
@@ -1248,9 +1279,17 @@
           {
             "tab": "快速开始",
             "groups": [
+              {
+                "group": "首页",
+                "pages": ["zh-CN/index"]
+              },
               {
                 "group": "概览",
-                "pages": ["zh-CN/index", "zh-CN/concepts/features", "zh-CN/start/showcase"]
+                "pages": ["zh-CN/start/showcase"]
+              },
+              {
+                "group": "核心概念",
+                "pages": ["zh-CN/concepts/features"]
               },
               {
                 "group": "第一步",
@@ -1276,7 +1315,6 @@
               {
                 "group": "安装方式",
                 "pages": [
-                  "zh-CN/install/node",
                   "zh-CN/install/docker",
                   "zh-CN/install/nix",
                   "zh-CN/install/ansible",
@@ -1340,11 +1378,11 @@
               {
                 "group": "配置",
                 "pages": [
-                  "zh-CN/start/pairing",
+                  "zh-CN/channels/pairing",
-                  "zh-CN/concepts/group-messages",
+                  "zh-CN/channels/group-messages",
-                  "zh-CN/concepts/groups",
+                  "zh-CN/channels/groups",
-                  "zh-CN/broadcast-groups",
+                  "zh-CN/channels/broadcast-groups",
-                  "zh-CN/concepts/channel-routing",
+                  "zh-CN/channels/channel-routing",
                   "zh-CN/channels/location",
                   "zh-CN/channels/troubleshooting"
                 ]
@@ -1366,6 +1404,10 @@
                   "zh-CN/concepts/oauth"
                 ]
               },
+              {
+                "group": "引导",
+                "pages": ["zh-CN/start/bootstrapping"]
+              },
               {
                 "group": "会话与记忆",
                 "pages": [
@@ -1426,38 +1468,45 @@
                 "pages": [
                   "zh-CN/tools/agent-send",
                   "zh-CN/tools/subagents",
-                  "zh-CN/multi-agent-sandbox-tools"
+                  "zh-CN/tools/multi-agent-sandbox-tools"
                 ]
               },
               {
-                "group": "技能与扩展",
+                "group": "技能",
                 "pages": [
                   "zh-CN/tools/slash-commands",
                   "zh-CN/tools/skills",
                   "zh-CN/tools/skills-config",
                   "zh-CN/tools/clawhub",
-                  "zh-CN/plugin",
+                  "zh-CN/tools/plugin"
-                  "zh-CN/plugins/voice-call",
-                  "zh-CN/plugins/zalouser"
                 ]
               },
+              {
+                "group": "扩展",
+                "pages": ["zh-CN/plugins/voice-call", "zh-CN/plugins/zalouser"]
+              },
               {
                 "group": "自动化",
                 "pages": [
-                  "zh-CN/hooks",
+                  "zh-CN/automation/hooks",
-                  "zh-CN/hooks/soul-evil",
                   "zh-CN/automation/cron-jobs",
                   "zh-CN/automation/cron-vs-heartbeat",
+                  "zh-CN/automation/troubleshooting",
                   "zh-CN/automation/webhook",
                   "zh-CN/automation/gmail-pubsub",
                   "zh-CN/automation/poll",
                   "zh-CN/automation/auth-monitoring"
                 ]
               },
+              {
+                "group": "Hooks",
+                "pages": ["zh-CN/hooks/soul-evil"]
+              },
               {
                 "group": "媒体与设备",
                 "pages": [
                   "zh-CN/nodes/index",
+                  "zh-CN/nodes/troubleshooting",
                   "zh-CN/nodes/images",
                   "zh-CN/nodes/audio",
                   "zh-CN/nodes/camera",
@@ -1473,11 +1522,11 @@
             "groups": [
               {
                 "group": "概览",
-                "pages": [
+                "pages": ["zh-CN/providers/index", "zh-CN/providers/models"]
-                  "zh-CN/providers/index",
+              },
-                  "zh-CN/providers/models",
+              {
-                  "zh-CN/concepts/models"
+                "group": "模型概念",
-                ]
+                "pages": ["zh-CN/concepts/models"]
               },
               {
                 "group": "配置",
@@ -1489,14 +1538,15 @@
                   "zh-CN/providers/anthropic",
                   "zh-CN/providers/openai",
                   "zh-CN/providers/openrouter",
-                  "zh-CN/bedrock",
+                  "zh-CN/providers/bedrock",
                   "zh-CN/providers/vercel-ai-gateway",
                   "zh-CN/providers/moonshot",
                   "zh-CN/providers/minimax",
                   "zh-CN/providers/opencode",
                   "zh-CN/providers/glm",
                   "zh-CN/providers/zai",
-                  "zh-CN/providers/synthetic"
+                  "zh-CN/providers/synthetic",
+                  "zh-CN/providers/qianfan"
                 ]
               }
             ]
@@ -1612,7 +1662,7 @@
                   "zh-CN/web/control-ui",
                   "zh-CN/web/dashboard",
                   "zh-CN/web/webchat",
-                  "zh-CN/tui"
+                  "zh-CN/web/tui"
                 ]
               }
             ]
@@ -1681,13 +1731,16 @@
               },
               {
                 "group": "技术参考",
+                "pages": ["zh-CN/reference/wizard", "zh-CN/reference/token-use"]
+              },
+              {
+                "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",
+                  "zh-CN/concepts/timezone"
-                  "zh-CN/token-use"
                 ]
               },
               {
@@ -1714,17 +1767,28 @@
               {
                 "group": "环境与调试",
                 "pages": [
-                  "zh-CN/environment",
+                  "zh-CN/help/environment",
-                  "zh-CN/debugging",
+                  "zh-CN/help/debugging",
-                  "zh-CN/testing",
+                  "zh-CN/help/testing",
-                  "zh-CN/scripts",
+                  "zh-CN/help/scripts"
-                  "zh-CN/reference/session-management-compaction"
                 ]
               },
               {
-                "group": "开发者工作流",
+                "group": "Node 运行时",
+                "pages": ["zh-CN/install/node"]
+              },
+              {
+                "group": "压缩机制内部参考",
+                "pages": ["zh-CN/reference/session-management-compaction"]
+              },
+              {
+                "group": "开发者设置",
                 "pages": ["zh-CN/start/setup"]
               },
+              {
+                "group": "贡献",
+                "pages": ["zh-CN/help/submitting-a-pr", "zh-CN/help/submitting-an-issue"]
+              },
               {
                 "group": "文档元信息",
                 "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"]

docs/experiments/plans/group-policy-hardening.md

@@ -36,5 +36,5 @@ false negatives when deciding whether to respond in DMs or groups.
 
 ## Related docs
 
-- [Group Chats](/concepts/groups)
+- [Group Chats](/channels/groups)
 - [Telegram Provider](/channels/telegram)

docs/gateway/configuration.md

@@ -289,7 +289,7 @@ process env is missing the key (same non-overriding rule):
 }
 ```
 
-See [/environment](/environment) for full precedence and sources.
+See [/environment](/help/environment) for full precedence and sources.
 
 ### `env.shellEnv` (optional)
 
@@ -788,7 +788,7 @@ levels in one gateway:
 - **Read-only** tools + workspace
 - **No filesystem access** (messaging/session tools only)
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence and
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence and
 additional examples.
 
 Full access (no sandbox):
@@ -2857,7 +2857,7 @@ Example:
 Controls plugin discovery, allow/deny, and per-plugin config. Plugins are loaded
 from `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, plus any
 `plugins.load.paths` entries. **Config changes require a gateway restart.**
-See [/plugin](/plugin) for full usage.
+See [/plugin](/tools/plugin) for full usage.
 
 Fields:
 

docs/gateway/heartbeat.md

@@ -200,7 +200,7 @@ Use `accountId` to target a specific account on multi-account channels like Tele
 - `session`: optional session key for heartbeat runs.
   - `main` (default): agent main session.
   - Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).
-  - Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).
+  - Session key formats: see [Sessions](/concepts/session) and [Groups](/channels/groups).
 - `target`:
   - `last` (default): deliver to the last used external channel.
   - explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.

docs/gateway/sandboxing.md

@@ -168,7 +168,7 @@ Debugging:
 
 Each agent can override sandbox + tools:
 `agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence.
 
 ## Minimal enable example
 
@@ -189,5 +189,5 @@ See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence.
 ## Related docs
 
 - [Sandbox Configuration](/gateway/configuration#agentsdefaults-sandbox)
-- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools)
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools)
 - [Security](/gateway/security)

docs/gateway/security/formal-verification.md

@@ -1,164 +0,0 @@
----
-title: Formal Verification (Security Models)
-summary: Machine-checked security models for OpenClaw’s highest-risk paths.
-permalink: /security/formal-verification/
----
-
-# Formal Verification (Security Models)
-
-This page tracks OpenClaw’s **formal security models** (TLA+/TLC today; more as needed).
-
-> Note: some older links may refer to the previous project name.
-
-**Goal (north star):** provide a machine-checked argument that OpenClaw enforces its
-intended security policy (authorization, session isolation, tool gating, and
-misconfiguration safety), under explicit assumptions.
-
-**What this is (today):** an executable, attacker-driven **security regression suite**:
-
-- Each claim has a runnable model-check over a finite state space.
-- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
-
-**What this is not (yet):** a proof that “OpenClaw is secure in all respects” or that the full TypeScript implementation is correct.
-
-## Where the models live
-
-Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models).
-
-## Important caveats
-
-- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
-- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds.
-- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
-
-## Reproducing results
-
-Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
-
-- CI-run models with public artifacts (counterexample traces, run logs)
-- a hosted “run this model” workflow for small, bounded checks
-
-Getting started:
-
-```bash
-git clone https://github.com/vignesh07/clawdbot-formal-models
-cd clawdbot-formal-models
-
-# Java 11+ required (TLC runs on the JVM).
-# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
-
-make <target>
-```
-
-### Gateway exposure and open gateway misconfiguration
-
-**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
-
-- Green runs:
-  - `make gateway-exposure-v2`
-  - `make gateway-exposure-v2-protected`
-- Red (expected):
-  - `make gateway-exposure-v2-negative`
-
-See also: `docs/gateway-exposure-matrix.md` in the models repo.
-
-### Nodes.run pipeline (highest-risk capability)
-
-**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
-
-- Green runs:
-  - `make nodes-pipeline`
-  - `make approvals-token`
-- Red (expected):
-  - `make nodes-pipeline-negative`
-  - `make approvals-token-negative`
-
-### Pairing store (DM gating)
-
-**Claim:** pairing requests respect TTL and pending-request caps.
-
-- Green runs:
-  - `make pairing`
-  - `make pairing-cap`
-- Red (expected):
-  - `make pairing-negative`
-  - `make pairing-cap-negative`
-
-### Ingress gating (mentions + control-command bypass)
-
-**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating.
-
-- Green:
-  - `make ingress-gating`
-- Red (expected):
-  - `make ingress-gating-negative`
-
-### Routing/session-key isolation
-
-**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
-
-- Green:
-  - `make routing-isolation`
-- Red (expected):
-  - `make routing-isolation-negative`
-
-## v1++: additional bounded models (concurrency, retries, trace correctness)
-
-These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out).
-
-### Pairing store concurrency / idempotency
-
-**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates).
-
-What it means:
-
-- Under concurrent requests, you can’t exceed `MaxPending` for a channel.
-- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows.
-
-- Green runs:
-  - `make pairing-race` (atomic/locked cap check)
-  - `make pairing-idempotency`
-  - `make pairing-refresh`
-  - `make pairing-refresh-race`
-- Red (expected):
-  - `make pairing-race-negative` (non-atomic begin/commit cap race)
-  - `make pairing-idempotency-negative`
-  - `make pairing-refresh-negative`
-  - `make pairing-refresh-race-negative`
-
-### Ingress trace correlation / idempotency
-
-**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries.
-
-What it means:
-
-- When one external event becomes multiple internal messages, every part keeps the same trace/event identity.
-- Retries do not result in double-processing.
-- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events.
-
-- Green:
-  - `make ingress-trace`
-  - `make ingress-trace2`
-  - `make ingress-idempotency`
-  - `make ingress-dedupe-fallback`
-- Red (expected):
-  - `make ingress-trace-negative`
-  - `make ingress-trace2-negative`
-  - `make ingress-idempotency-negative`
-  - `make ingress-dedupe-fallback-negative`
-
-### Routing dmScope precedence + identityLinks
-
-**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links).
-
-What it means:
-
-- Channel-specific dmScope overrides must win over global defaults.
-- identityLinks should collapse only within explicit linked groups, not across unrelated peers.
-
-- Green:
-  - `make routing-precedence`
-  - `make routing-identitylinks`
-- Red (expected):
-  - `make routing-precedence-negative`
-  - `make routing-identitylinks-negative`

docs/gateway/security/index.md

@@ -175,7 +175,7 @@ Plugins run **in-process** with the Gateway. Treat them as trusted code:
   - OpenClaw uses `npm pack` and then runs `npm install --omit=dev` in that directory (npm lifecycle scripts can execute code during install).
   - Prefer pinned, exact versions (`@scope/pkg@1.2.3`), and inspect the unpacked code on disk before enabling.
 
-Details: [Plugins](/plugin)
+Details: [Plugins](/tools/plugin)
 
 ## DM access model (pairing / allowlist / open / disabled)
 
@@ -193,7 +193,7 @@ openclaw pairing list <channel>
 openclaw pairing approve <channel> <code>
 ```
 
-Details + files on disk: [Pairing](/start/pairing)
+Details + files on disk: [Pairing](/channels/pairing)
 
 ## DM session isolation (multi-user mode)
 
@@ -229,7 +229,7 @@ OpenClaw has two separate “who can trigger me?” layers:
     - `channels.discord.guilds` / `channels.slack.channels`: per-surface allowlists + mention defaults.
   - **Security note:** treat `dmPolicy="open"` and `groupPolicy="open"` as last-resort settings. They should be barely used; prefer pairing + allowlists unless you fully trust every member of the room.
 
-Details: [Configuration](/gateway/configuration) and [Groups](/concepts/groups)
+Details: [Configuration](/gateway/configuration) and [Groups](/channels/groups)
 
 ## Prompt injection (what it is, why it matters)
 
@@ -627,7 +627,7 @@ access those accounts and data. Treat browser profiles as **sensitive state**:
 
 With multi-agent routing, each agent can have its own sandbox + tool policy:
 use this to give **full access**, **read-only**, or **no access** per agent.
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for full details
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for full details
 and precedence rules.
 
 Common use cases:

docs/gateway/troubleshooting.md

@@ -56,8 +56,8 @@ Common signatures:
 Related:
 
 - [/channels/troubleshooting](/channels/troubleshooting)
-- [/start/pairing](/start/pairing)
+- [/channels/pairing](/channels/pairing)
-- [/concepts/groups](/concepts/groups)
+- [/channels/groups](/channels/groups)
 
 ## Dashboard control ui connectivity
 

docs/help/faq.md

@@ -707,7 +707,7 @@ See [Models](/cli/models) and [OAuth](/concepts/oauth).
 
 ### Is AWS Bedrock supported
 
-Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
+Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
 
 ### How does Codex auth work
 
@@ -1177,7 +1177,7 @@ Yes - if your private traffic is **DMs** and your public traffic is **groups**.
 
 Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`.
 
-Setup walkthrough + example config: [Groups: personal DMs + public groups](/concepts/groups#pattern-personal-dms-public-groups-single-agent)
+Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent)
 
 Key config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)
 
@@ -1427,7 +1427,7 @@ The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **a
 - **Sub-agents:** spawn background work from a main agent when you want parallelism.
 - **TUI:** connect to the Gateway and switch agents/sessions.
 
-Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui).
+Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui).
 
 ### Can the OpenClaw browser run headless
 
@@ -1681,7 +1681,7 @@ You can also define inline env vars in config (applied only if missing from the
 }
 ```
 
-See [/environment](/environment) for full precedence and sources.
+See [/environment](/help/environment) for full precedence and sources.
 
 ### I started the Gateway via the service and my env vars disappeared What now
 
@@ -1729,7 +1729,7 @@ openclaw models status
 ```
 
 Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
-See [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).
+See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment).
 
 ## Sessions and multiple chats
 
@@ -1902,11 +1902,11 @@ Two common causes:
 - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
 - You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted.
 
-See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
 
 ### Do groupsthreads share context with DMs
 
-Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).
+Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
 
 ### How many workspaces and agents can I create
 
@@ -1994,7 +1994,7 @@ Safe options:
 
 - `/model` in chat (quick, per-session)
 - `openclaw models set ...` (updates just model config)
-- `openclaw configure --section models` (interactive)
+- `openclaw configure --section model` (interactive)
 - edit `agents.defaults.model` in `~/.openclaw/openclaw.json`
 
 Avoid `config.apply` with a partial object unless you intend to replace the whole config.
@@ -2609,7 +2609,7 @@ openclaw logs --follow
 In the TUI, use `/status` to see the current state. If you expect replies in a chat
 channel, make sure delivery is enabled (`/deliver on`).
 
-Docs: [TUI](/tui), [Slash commands](/tools/slash-commands).
+Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands).
 
 ### How do I completely stop then start the Gateway
 
@@ -2701,7 +2701,7 @@ credentials or revoke access without impacting your personal accounts.
 Start small. Give access only to the tools and accounts you actually need, and expand
 later if required.
 
-Docs: [Security](/gateway/security), [Pairing](/start/pairing).
+Docs: [Security](/gateway/security), [Pairing](/channels/pairing).
 
 ### Can I give it autonomy over my text messages and is that safe
 

docs/help/troubleshooting.md

@@ -83,7 +83,7 @@ flowchart TD
 
     - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
     - [/channels/troubleshooting](/channels/troubleshooting)
-    - [/start/pairing](/start/pairing)
+    - [/channels/pairing](/channels/pairing)
 
   </Accordion>
 

docs/hooks/soul-evil.md

@@ -66,4 +66,4 @@ Create `SOUL_EVIL.md` in the agent workspace root (next to `SOUL.md`).
 
 ## See Also
 
-- [Hooks](/hooks)
+- [Hooks](/automation/hooks)

docs/install/ansible.md

@@ -107,7 +107,7 @@ Should show **only port 22** (SSH) open. All other services (gateway, Docker) ar
 
 Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for sandbox configuration.
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration.
 
 ## Manual Installation
 
@@ -205,4 +205,4 @@ For detailed security architecture and troubleshooting:
 - [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) — full deployment guide
 - [Docker](/install/docker) — containerized gateway setup
 - [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
-- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) — per-agent isolation
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — per-agent isolation

docs/install/docker.md

@@ -336,7 +336,7 @@ mixed access levels in one gateway:
 - Read-only tools + read-only workspace (family/work agent)
 - No filesystem/shell tools (public agent)
 
-See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples,
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for examples,
 precedence, and troubleshooting.
 
 ### Default behavior

docs/network.md

@@ -21,7 +21,7 @@ devices across localhost, LAN, and tailnet.
 
 ## Pairing + identity
 
-- [Pairing overview (DM + nodes)](/start/pairing)
+- [Pairing overview (DM + nodes)](/channels/pairing)
 - [Gateway-owned node pairing](/gateway/pairing)
 - [Devices CLI (pairing + token rotation)](/cli/devices)
 - [Pairing CLI (DM approvals)](/cli/pairing)

docs/plugins/manifest.md

@@ -13,7 +13,7 @@ OpenClaw uses this manifest to validate configuration **without executing plugin
 code**. Missing or invalid manifests are treated as plugin errors and block
 config validation.
 
-See the full plugin system guide: [Plugins](/plugin).
+See the full plugin system guide: [Plugins](/tools/plugin).
 
 ## Required fields
 

docs/prose.md

@@ -31,7 +31,7 @@ Restart the Gateway after enabling the plugin.
 
 Dev/local checkout: `openclaw plugins install ./extensions/open-prose`
 
-Related docs: [Plugins](/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
+Related docs: [Plugins](/tools/plugin), [Plugin manifest](/plugins/manifest), [Skills](/tools/skills).
 
 ## Slash command
 

docs/providers/index.md

@@ -43,7 +43,7 @@ See [Venice AI](/providers/venice).
 - [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
 - [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
 - [OpenCode Zen](/providers/opencode)
-- [Amazon Bedrock](/bedrock)
+- [Amazon Bedrock](/providers/bedrock)
 - [Z.AI](/providers/zai)
 - [Xiaomi](/providers/xiaomi)
 - [GLM models](/providers/glm)

docs/providers/models.md

@@ -45,7 +45,7 @@ See [Venice AI](/providers/venice).
 - [GLM models](/providers/glm)
 - [MiniMax](/providers/minimax)
 - [Venice (Venice AI)](/providers/venice)
-- [Amazon Bedrock](/bedrock)
+- [Amazon Bedrock](/providers/bedrock)
 - [Qianfan](/providers/qianfan)
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,

docs/providers/qianfan.md

@@ -32,7 +32,7 @@ openclaw onboard --auth-choice qianfan-api-key
 
 ## Related Documentation
 
-- [OpenClaw Configuration](/configuration)
+- [OpenClaw Configuration](/gateway/configuration)
 - [Model Providers](/concepts/model-providers)
-- [Agent Setup](/agents)
+- [Agent Setup](/concepts/agent)
 - [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)

docs/refactor/plugin-sdk.md

@@ -211,4 +211,4 @@ Notes:
 - New connector templates depend only on SDK + runtime.
 - External plugins can be developed and updated without core source access.
 
-Related docs: [Plugins](/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).
+Related docs: [Plugins](/tools/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).

docs/reference/api-usage-costs.md

@@ -29,7 +29,7 @@ OpenClaw features that can generate provider usage or paid API calls.
 - `openclaw status --usage` and `openclaw channels list` show provider **usage windows**
   (quota snapshots, not per-message costs).
 
-See [Token use & costs](/token-use) for details and examples.
+See [Token use & costs](/reference/token-use) for details and examples.
 
 ## How keys are discovered
 
@@ -48,7 +48,7 @@ OpenClaw can pick up credentials from:
 Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
 primary source of usage and cost.
 
-See [Models](/providers/models) for pricing config and [Token use & costs](/token-use) for display.
+See [Models](/providers/models) for pricing config and [Token use & costs](/reference/token-use) for display.
 
 ### 2) Media understanding (audio/image/video)
 

docs/reference/session-management-compaction.md

@@ -154,7 +154,7 @@ If you’re tuning limits:
 - The context window comes from the model catalog (and can be overridden via config).
 - `contextTokens` in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.
 
-For more, see [/token-use](/token-use).
+For more, see [/token-use](/reference/token-use).
 
 ---
 

docs/reference/test.md

@@ -7,7 +7,7 @@ title: "Tests"
 
 # Tests
 
-- Full testing kit (suites, live, Docker): [Testing](/testing)
+- Full testing kit (suites, live, Docker): [Testing](/help/testing)
 
 - `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
 - `pnpm test:coverage`: Runs Vitest with V8 coverage. Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic.

docs/start/docs-directory.md

@@ -19,7 +19,7 @@ For a complete map of the docs, see [Docs hubs](/start/hubs).
 - [Slash commands](/tools/slash-commands)
 - [Multi-agent routing](/concepts/multi-agent)
 - [Updating and rollback](/install/updating)
-- [Pairing (DM and nodes)](/start/pairing)
+- [Pairing (DM and nodes)](/channels/pairing)
 - [Nix mode](/install/nix)
 - [OpenClaw assistant setup](/start/openclaw)
 - [Skills](/tools/skills)
@@ -41,8 +41,8 @@ For a complete map of the docs, see [Docs hubs](/start/hubs).
 - [Mattermost (plugin)](/channels/mattermost)
 - [BlueBubbles (iMessage)](/channels/bluebubbles)
 - [iMessage (legacy)](/channels/imessage)
-- [Groups](/concepts/groups)
+- [Groups](/channels/groups)
-- [WhatsApp group messages](/concepts/group-messages)
+- [WhatsApp group messages](/channels/group-messages)
 - [Media images](/nodes/images)
 - [Media audio](/nodes/audio)
 

docs/start/getting-started.md

@@ -115,6 +115,6 @@ If the Control UI loads, your Gateway is ready for use.
 
 ## Next steps
 
-- DM safety and approvals: [Pairing](/start/pairing)
+- DM safety and approvals: [Pairing](/channels/pairing)
 - Connect more channels: [Channels](/channels)
 - Advanced workflows and from source: [Setup](/start/setup)

docs/start/hubs.md

@@ -61,9 +61,9 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Presence](/concepts/presence)
 - [Discovery + transports](/gateway/discovery)
 - [Bonjour](/gateway/bonjour)
-- [Channel routing](/concepts/channel-routing)
+- [Channel routing](/channels/channel-routing)
-- [Groups](/concepts/groups)
+- [Groups](/channels/groups)
-- [Group messages](/concepts/group-messages)
+- [Group messages](/channels/group-messages)
 - [Model failover](/concepts/model-failover)
 - [OAuth](/concepts/oauth)
 
@@ -118,7 +118,7 @@ Use these hubs to discover every page, including deep dives and reference docs t
 - [Models](/concepts/models)
 - [Sub-agents](/tools/subagents)
 - [Agent send CLI](/tools/agent-send)
-- [Terminal UI](/tui)
+- [Terminal UI](/web/tui)
 - [Browser control](/tools/browser)
 - [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
 - [Polls](/automation/poll)

docs/tools/index.md

@@ -166,7 +166,7 @@ Example (allow only file tools + browser):
 ## Plugins + tools
 
 Plugins can register **additional tools** (and CLI commands) beyond the core set.
-See [Plugins](/plugin) for install + config, and [Skills](/tools/skills) for how
+See [Plugins](/tools/plugin) for install + config, and [Skills](/tools/skills) for how
 tool usage guidance is injected into prompts. Some plugins ship their own skills
 alongside tools (for example, the voice-call plugin).
 

docs/tools/lobster.md

@@ -331,7 +331,7 @@ OpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep,
 
 ## Learn more
 
-- [Plugins](/plugin)
+- [Plugins](/tools/plugin)
 - [Plugin tool authoring](/plugins/agent-tools)
 
 ## Case study: community workflows

docs/tools/skills.md

@@ -44,7 +44,7 @@ Plugins can ship their own skills by listing `skills` directories in
 `openclaw.plugin.json` (paths relative to the plugin root). Plugin skills load
 when the plugin is enabled and participate in the normal skill precedence rules.
 You can gate them via `metadata.openclaw.requires.config` on the plugin’s config
-entry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the
+entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the
 tool surface those skills teach.
 
 ## ClawHub (install + sync)

docs/zh-CN/automation/hooks.md

@@ -9,7 +9,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: 853227a0f1abd20790b425fa64dda60efc6b5f93c1b13ecd2dcb788268f71d79
-  source_path: hooks.md
+  source_path: automation/hooks.md
   workflow: 15
 ---
 
@@ -24,7 +24,7 @@ Hooks 是在事件发生时运行的小脚本。有两种类型：
 - **Hooks**（本页）：当智能体事件触发时在 Gateway 网关内运行，如 `/new`、`/reset`、`/stop` 或生命周期事件。
 - **Webhooks**：外部 HTTP webhooks，让其他系统触发 OpenClaw 中的工作。参见 [Webhook Hooks](/automation/webhook) 或使用 `openclaw webhooks` 获取 Gmail 助手命令。
 
-Hooks 也可以捆绑在插件中；参见 [插件](/plugin#plugin-hooks)。
+Hooks 也可以捆绑在插件中；参见 [插件](/tools/plugin#plugin-hooks)。
 
 常见用途：
 

docs/zh-CN/automation/troubleshooting.md

@@ -0,0 +1,8 @@
+---
+summary: 自动化故障排查：排查 cron 和 heartbeat 调度与投递问题
+title: 自动化故障排查
+---
+
+# 自动化故障排查
+
+该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Automation Troubleshooting](/automation/troubleshooting)。

docs/zh-CN/channels/bluebubbles.md

@@ -25,7 +25,7 @@ x-i18n:
 - OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。
 - 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。
 - 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。
-- 配对/白名单的工作方式与其他渠道相同（`/start/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
+- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。
 - 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。
 - 高级功能：编辑、撤回、回复线程、消息效果、群组管理。
 
@@ -80,7 +80,7 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
 - 批准方式：
   - `openclaw pairing list bluebubbles`
   - `openclaw pairing approve bluebubbles <CODE>`
-- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
+- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
 
 群组：
 
@@ -268,4 +268,4 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。
 - OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。
 - 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。
 
-有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/plugins)指南。
+有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。

docs/zh-CN/channels/broadcast-groups.md

@@ -10,7 +10,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: eaeb4035912c49413e012177cf0bd28b348130d30d3317674418dca728229b70
-  source_path: broadcast-groups.md
+  source_path: channels/broadcast-groups.md
   workflow: 15
 ---
 
@@ -444,6 +444,6 @@ interface OpenClawConfig {
 
 ## 另请参阅
 
-- [多智能体配置](/multi-agent-sandbox-tools)
+- [多智能体配置](/tools/multi-agent-sandbox-tools)
-- [路由配置](/concepts/channel-routing)
+- [路由配置](/channels/channel-routing)
 - [会话管理](/concepts/sessions)

docs/zh-CN/channels/channel-routing.md

@@ -8,7 +8,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: 1a322b5187e32c82fc1e8aac02437e2eeb7ba84e7b3a1db89feeab1dcf7dbbab
-  source_path: concepts/channel-routing.md
+  source_path: channels/channel-routing.md
   workflow: 14
 ---
 
@@ -73,7 +73,7 @@ OpenClaw 将回复**路由回消息来源的渠道**。模型不会选择渠道
 }
 ```
 
-参见：[广播组](/broadcast-groups)。
+参见：[广播组](/channels/broadcast-groups)。
 
 ## 配置概览
 

docs/zh-CN/channels/group-messages.md

@@ -8,7 +8,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
-  source_path: concepts/group-messages.md
+  source_path: channels/group-messages.md
   workflow: 15
 ---
 

docs/zh-CN/channels/groups.md

@@ -8,7 +8,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: b727a053edf51f6e7b5c0c324c2fc9c9789a9796c37f622418bd555e8b5a0ec4
-  source_path: concepts/groups.md
+  source_path: channels/groups.md
   workflow: 15
 ---
 
@@ -376,4 +376,4 @@ requireMention? 是 -> 被提及? 否 -> 仅存储为上下文
 
 ## WhatsApp 特定内容
 
-参见[群消息](/concepts/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。
+参见[群消息](/channels/group-messages)了解 WhatsApp 专有行为（历史注入、提及处理详情）。

docs/zh-CN/channels/imessage.md

@@ -205,7 +205,7 @@ exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
 - 批准方式：
   - `openclaw pairing list imessage`
   - `openclaw pairing approve imessage <CODE>`
-- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/start/pairing)
+- 配对是 iMessage 私信的默认令牌交换方式。详情：[配对](/channels/pairing)
 
 群组：
 

docs/zh-CN/channels/index.md

@@ -46,7 +46,7 @@ OpenClaw 可以在你已经使用的任何聊天应用上与你交流。每个
 - 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。
 - 最快的设置方式通常是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，
   并在磁盘上存储更多状态。
-- 群组行为因渠道而异；参见[群组](/concepts/groups)。
+- 群组行为因渠道而异；参见[群组](/channels/groups)。
 - 为安全起见，私信配对和允许列表会被强制执行；参见[安全](/gateway/security)。
 - Telegram 内部机制：[grammY 说明](/channels/grammy)。
 - 故障排除：[渠道故障排除](/channels/troubleshooting)。

docs/zh-CN/channels/matrix.md

@@ -36,7 +36,7 @@ openclaw plugins install ./extensions/matrix
 
 如果你在配置/新手引导期间选择 Matrix 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 设置
 

docs/zh-CN/channels/mattermost.md

@@ -37,7 +37,7 @@ openclaw plugins install ./extensions/mattermost
 
 如果你在配置/新手引导期间选择 Mattermost 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 快速设置
 

docs/zh-CN/channels/msteams.md

@@ -43,7 +43,7 @@ openclaw plugins install ./extensions/msteams
 如果你在配置/新手引导过程中选择 Teams 并检测到 git 检出，
 OpenClaw 将自动提供本地安装路径。
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 快速设置（初学者）
 

docs/zh-CN/channels/nextcloud-talk.md

@@ -35,7 +35,7 @@ openclaw plugins install ./extensions/nextcloud-talk
 如果你在配置/新手引导过程中选择了 Nextcloud Talk，并且检测到 git 检出，
 OpenClaw 将自动提供本地安装路径。
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 快速设置（新手）
 

docs/zh-CN/channels/pairing.md

@@ -10,7 +10,7 @@ x-i18n:
   model: claude-opus-4-5
   provider: pi
   source_hash: c46a5c39f289c8fd0783baacd927f550c3d3ae8889a7bc7de133b795f16fa08a
-  source_path: start/pairing.md
+  source_path: channels/pairing.md
   workflow: 15
 ---
 

docs/zh-CN/channels/signal.md

@@ -116,7 +116,7 @@ x-i18n:
 - 通过以下方式批准：
   - `openclaw pairing list signal`
   - `openclaw pairing approve signal <CODE>`
-- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/start/pairing)
+- 配对是 Signal 私信的默认令牌交换方式。详情：[配对](/channels/pairing)
 - 仅有 UUID 的发送者（来自 `sourceUuid`）在 `channels.signal.allowFrom` 中存储为 `uuid:<id>`。
 
 群组：

docs/zh-CN/channels/telegram.md

@@ -356,7 +356,7 @@ Telegram 功能可以在两个级别配置（上面显示的对象形式；旧
 - 批准方式：
   - `openclaw pairing list telegram`
   - `openclaw pairing approve telegram <CODE>`
-- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/start/pairing)
+- 配对是 Telegram 私信使用的默认 token 交换。详情：[配对](/channels/pairing)
 - `channels.telegram.allowFrom` 接受数字用户 ID（推荐）或 `@username` 条目。这**不是**机器人用户名；使用人类发送者的 ID。向导接受 `@username` 并在可能时将其解析为数字 ID。
 
 #### 查找你的 Telegram 用户 ID

docs/zh-CN/channels/tlon.md

@@ -34,7 +34,7 @@ openclaw plugins install @openclaw/tlon
 openclaw plugins install ./extensions/tlon
 ```
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 设置
 

docs/zh-CN/channels/twitch.md

@@ -32,7 +32,7 @@ openclaw plugins install @openclaw/twitch
 openclaw plugins install ./extensions/twitch
 ```
 
-详情：[插件](/plugin)
+详情：[插件](/tools/plugin)
 
 ## 快速设置（新手）
 

docs/zh-CN/channels/zalo.md

@@ -22,7 +22,7 @@ Zalo 以插件形式提供，不包含在核心安装中。
 
 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalo`
 - 或在新手引导期间选择 **Zalo** 并确认安装提示
-- 详情：[插件](/plugin)
+- 详情：[插件](/tools/plugin)
 
 ## 快速设置（初学者）
 
@@ -111,7 +111,7 @@ Zalo 是一款专注于越南市场的即时通讯应用；其 Bot API 让 Gatew
 - 通过以下方式批准：
   - `openclaw pairing list zalo`
   - `openclaw pairing approve zalo <CODE>`
-- 配对是默认的令牌交换方式。详情：[配对](/start/pairing)
+- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing)
 - `channels.zalo.allowFrom` 接受数字用户 ID（无用户名查找功能）。
 
 ## 长轮询与 webhook

docs/zh-CN/channels/zalouser.md

@@ -25,7 +25,7 @@ Zalo Personal 作为插件提供，不包含在核心安装中。
 
 - 通过 CLI 安装：`openclaw plugins install @openclaw/zalouser`
 - 或从源码检出安装：`openclaw plugins install ./extensions/zalouser`
-- 详情：[插件](/plugin)
+- 详情：[插件](/tools/plugin)
 
 ## 前置条件：zca-cli
 

docs/zh-CN/cli/hooks.md

@@ -19,8 +19,8 @@ x-i18n:
 
 相关内容：
 
-- 钩子：[钩子](/hooks)
+- 钩子：[钩子](/automation/hooks)
-- 插件钩子：[插件](/plugin#plugin-hooks)
+- 插件钩子：[插件](/tools/plugin#plugin-hooks)
 
 ## 列出所有钩子
 
@@ -255,7 +255,7 @@ openclaw hooks enable session-memory
 
 **输出：** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
 
-**参见：** [session-memory 文档](/hooks#session-memory)
+**参见：** [session-memory 文档](/automation/hooks#session-memory)
 
 ### command-logger
 
@@ -282,7 +282,7 @@ cat ~/.openclaw/logs/commands.log | jq .
 grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 ```
 
-**参见：** [command-logger 文档](/hooks#command-logger)
+**参见：** [command-logger 文档](/automation/hooks#command-logger)
 
 ### soul-evil
 
@@ -308,4 +308,4 @@ openclaw hooks enable soul-evil
 openclaw hooks enable boot-md
 ```
 
-**参见：** [boot-md 文档](/hooks#boot-md)
+**参见：** [boot-md 文档](/automation/hooks#boot-md)