auto create develop branch too

- Remove undefined should_bump_version input from release.yml
- Fix Discord action variable expansion (single to double quotes)
- Add has_changes gate to changelog and test jobs
- Use unique heredoc delimiter to prevent collision with commit messages

.github/actions/discord-notify/action.yml

@@ -0,0 +1,69 @@
+name: Discord Notify
+description: Send notifications to Discord webhook
+
+inputs:
+  webhook_url:
+    description: Discord webhook URL
+    required: true
+  title:
+    description: Notification title
+    required: true
+  description:
+    description: Notification description
+    required: true
+  color:
+    description: Embed color (decimal)
+    required: false
+    default: "3447003"
+  username:
+    description: Bot username
+    required: false
+    default: "OpenClaw CI"
+  avatar_url:
+    description: Bot avatar URL
+    required: false
+    default: "https://avatars.githubusercontent.com/u/182880377"
+  timestamp:
+    description: Include timestamp
+    required: false
+    default: "true"
+  fields:
+    description: JSON array of embed fields
+    required: false
+    default: "[]"
+
+runs:
+  using: composite
+  steps:
+    - name: Send Discord notification
+      shell: bash
+      run: |
+        TIMESTAMP=""
+        if [ "${{ inputs.timestamp }}" = "true" ]; then
+          TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+        fi
+
+        # Build JSON payload with jq to handle escaping properly
+        PAYLOAD=$(jq -n \
+          --arg username "${{ inputs.username }}" \
+          --arg avatar_url "${{ inputs.avatar_url }}" \
+          --arg title "${{ inputs.title }}" \
+          --arg description "${{ inputs.description }}" \
+          --argjson color "${{ inputs.color }}" \
+          --argjson fields '${{ inputs.fields }}' \
+          --arg timestamp "$TIMESTAMP" \
+          --argjson add_timestamp "${{ inputs.timestamp == 'true' }}" \
+          '{
+            username: $username,
+            avatar_url: $avatar_url,
+            embeds: [{
+              title: $title,
+              description: $description,
+              color: $color,
+              fields: $fields
+            } + (if $add_timestamp then {timestamp: $timestamp} else {} end)]
+          }')
+
+        curl -sS -H "Content-Type: application/json" \
+          -d "$PAYLOAD" \
+          "${{ inputs.webhook_url }}"

.github/workflows/ci.yml

@@ -1,8 +1,19 @@
 name: CI
 
 on:
-  push:
   pull_request:
+  workflow_call:
+    # Called by testing-strategy.yml for staged releases
+    inputs:
+      test_stage:
+        description: "Testing stage: develop, alpha, beta, or stable. Controls which platform tests run."
+        required: false
+        type: string
+        default: ""
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
 
 jobs:
   install-check:
@@ -182,10 +193,16 @@ jobs:
           fi
 
   checks-windows:
+    # Windows tests: beta+ staging only (not on regular PRs to save compute)
+    if: |
+      inputs.test_stage == 'beta' ||
+      inputs.test_stage == 'stable'
     runs-on: blacksmith-4vcpu-windows-2025
     env:
       NODE_OPTIONS: --max-old-space-size=4096
-      CLAWDBOT_TEST_WORKERS: 1
+      # Keep total concurrency predictable on the 4 vCPU runner:
+      # `scripts/test-parallel.mjs` runs some vitest suites in parallel processes.
+      OPENCLAW_TEST_WORKERS: 2
     defaults:
       run:
         shell: bash
@@ -208,6 +225,25 @@ jobs:
         with:
           submodules: false
 
+      - name: Try to exclude workspace from Windows Defender (best-effort)
+        shell: pwsh
+        run: |
+          $cmd = Get-Command Add-MpPreference -ErrorAction SilentlyContinue
+          if (-not $cmd) {
+            Write-Host "Add-MpPreference not available, skipping Defender exclusions."
+            exit 0
+          }
+
+          try {
+            # Defender sometimes intercepts process spawning (vitest workers). If this fails
+            # (eg hardened images), keep going and rely on worker limiting above.
+            Add-MpPreference -ExclusionPath "$env:GITHUB_WORKSPACE" -ErrorAction Stop
+            Add-MpPreference -ExclusionProcess "node.exe" -ErrorAction Stop
+            Write-Host "Defender exclusions applied."
+          } catch {
+            Write-Warning "Failed to apply Defender exclusions, continuing. $($_.Exception.Message)"
+          }
+
       - name: Checkout submodules (retry)
         run: |
           set -euo pipefail
@@ -270,14 +306,9 @@ jobs:
         run: ${{ matrix.command }}
 
   checks-macos:
-    if: github.event_name == 'pull_request'
+    # macOS tests: stable staging only (not on regular PRs to save compute)
+    if: inputs.test_stage == 'stable'
     runs-on: macos-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - task: test
-            command: pnpm test
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -297,6 +328,7 @@ jobs:
           done
           exit 1
 
+      # --- Node/pnpm setup (for TS tests) ---
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -336,71 +368,20 @@ jobs:
           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 all checks sequentially (fast gates first) ---
+      - name: TS tests (macOS)
         env:
           NODE_OPTIONS: --max-old-space-size=4096
-        run: ${{ matrix.command }}
-
-  macos-app:
-    if: github.event_name == 'pull_request'
-    runs-on: macos-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - task: lint
-            command: |
-              swiftlint --config .swiftlint.yml
-              swiftformat --lint apps/macos/Sources --config .swiftformat
-          - task: build
-            command: |
-              set -euo pipefail
-              for attempt in 1 2 3; do
-                if swift build --package-path apps/macos --configuration release; then
-                  exit 0
-                fi
-                echo "swift build failed (attempt $attempt/3). Retrying…"
-                sleep $((attempt * 20))
-              done
-              exit 1
-          - task: test
-            command: |
-              set -euo pipefail
-              for attempt in 1 2 3; do
-                if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
-                  exit 0
-                fi
-                echo "swift test failed (attempt $attempt/3). Retrying…"
-                sleep $((attempt * 20))
-              done
-              exit 1
-    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
+        run: pnpm test
 
+      # --- Xcode/Swift setup ---
       - name: Select Xcode 26.1
         run: |
           sudo xcode-select -s /Applications/Xcode_26.1.app
           xcodebuild -version
 
       - name: Install XcodeGen / SwiftLint / SwiftFormat
-        run: |
-          brew install xcodegen swiftlint swiftformat
+        run: brew install xcodegen swiftlint swiftformat
 
       - name: Show toolchain
         run: |
@@ -408,8 +389,35 @@ jobs:
           xcodebuild -version
           swift --version
 
-      - name: Run ${{ matrix.task }}
-        run: ${{ matrix.command }}
+      - name: Swift lint
+        run: |
+          swiftlint --config .swiftlint.yml
+          swiftformat --lint apps/macos/Sources --config .swiftformat
+
+      - name: Swift build (release)
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if swift build --package-path apps/macos --configuration release; then
+              exit 0
+            fi
+            echo "swift build failed (attempt $attempt/3). Retrying…"
+            sleep $((attempt * 20))
+          done
+          exit 1
+
+      - name: Swift test
+        run: |
+          set -euo pipefail
+          for attempt in 1 2 3; do
+            if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
+              exit 0
+            fi
+            echo "swift test failed (attempt $attempt/3). Retrying…"
+            sleep $((attempt * 20))
+          done
+          exit 1
+
   ios:
     if: false # ignore iOS in CI for now
     runs-on: macos-latest

.github/workflows/deployment-strategy.yml

@@ -0,0 +1,349 @@
+name: Deployment Strategy
+
+# Reusable deployment workflow for staged releases
+#
+# Deployment targets by stage:
+# - alpha: npm @alpha tag only
+# - beta: npm @beta tag + Docker (ghcr.io) beta tag
+# - stable: npm @latest + Docker latest + multi-arch manifest
+
+on:
+  workflow_call:
+    inputs:
+      deployment_stage:
+        description: "Deployment stage: alpha, beta, or stable"
+        required: true
+        type: string
+      app_version:
+        description: "Version of the application to deploy"
+        required: true
+        type: string
+      source_branch:
+        description: "Source branch for deployment"
+        required: true
+        type: string
+    outputs:
+      deployment_status:
+        description: "Status of the deployment"
+        value: ${{ jobs.deploy-summary.outputs.status }}
+      npm_url:
+        description: "npm package URL"
+        value: ${{ jobs.deploy-summary.outputs.npm_url }}
+      docker_url:
+        description: "Docker image URL"
+        value: ${{ jobs.deploy-summary.outputs.docker_url }}
+    secrets:
+      NPM_TOKEN:
+        required: false
+      DISCORD_WEBHOOK_URL:
+        required: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  # npm publish (all stages)
+  npm-publish:
+    name: npm Publish (${{ inputs.deployment_stage }})
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    outputs:
+      status: ${{ steps.publish.outputs.status }}
+      npm_url: ${{ steps.publish.outputs.npm_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_branch }}
+          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
+          registry-url: "https://registry.npmjs.org"
+
+      - 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: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Build
+        run: pnpm build
+
+      - name: Determine npm tag
+        id: npm-tag
+        run: |
+          case "${{ inputs.deployment_stage }}" in
+            alpha)
+              echo "tag=alpha" >> $GITHUB_OUTPUT
+              ;;
+            beta)
+              echo "tag=beta" >> $GITHUB_OUTPUT
+              ;;
+            stable)
+              echo "tag=latest" >> $GITHUB_OUTPUT
+              ;;
+          esac
+
+      - name: Publish to npm
+        id: publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "NPM_TOKEN not set, skipping publish"
+            echo "status=skipped" >> $GITHUB_OUTPUT
+            echo "npm_url=" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          NPM_TAG="${{ steps.npm-tag.outputs.tag }}"
+
+          if npm publish --tag "$NPM_TAG" --access public; then
+            echo "status=success" >> $GITHUB_OUTPUT
+            echo "npm_url=https://www.npmjs.com/package/openclaw/v/${{ inputs.app_version }}" >> $GITHUB_OUTPUT
+          else
+            echo "status=failed" >> $GITHUB_OUTPUT
+            echo "npm_url=" >> $GITHUB_OUTPUT
+            exit 1
+          fi
+
+  # Docker build - amd64 (beta+ only)
+  docker-amd64:
+    name: Docker amd64 (${{ inputs.deployment_stage }})
+    if: inputs.deployment_stage != 'alpha'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_branch }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=${{ inputs.app_version }}-amd64
+            type=raw,value=${{ inputs.deployment_stage }}-amd64
+
+      - name: Build and push amd64
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+          push: true
+
+  # Docker build - arm64 (beta+ only)
+  docker-arm64:
+    name: Docker arm64 (${{ inputs.deployment_stage }})
+    if: inputs.deployment_stage != 'alpha'
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_branch }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=${{ inputs.app_version }}-arm64
+            type=raw,value=${{ inputs.deployment_stage }}-arm64
+
+      - name: Build and push arm64
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/arm64
+          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+          push: true
+
+  # Create multi-arch manifest (beta+ only)
+  docker-manifest:
+    name: Docker Manifest (${{ inputs.deployment_stage }})
+    if: inputs.deployment_stage != 'alpha'
+    runs-on: ubuntu-latest
+    needs: [docker-amd64, docker-arm64]
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      docker_url: ${{ steps.manifest.outputs.docker_url }}
+    steps:
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest
+        id: manifest
+        run: |
+          STAGE="${{ inputs.deployment_stage }}"
+          VERSION="${{ inputs.app_version }}"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+
+          # Create version manifest
+          docker buildx imagetools create \
+            -t "${IMAGE}:${VERSION}" \
+            "${IMAGE}:${VERSION}-amd64" \
+            "${IMAGE}:${VERSION}-arm64"
+
+          # Create stage manifest (beta or latest)
+          if [ "$STAGE" = "stable" ]; then
+            docker buildx imagetools create \
+              -t "${IMAGE}:latest" \
+              "${IMAGE}:${VERSION}-amd64" \
+              "${IMAGE}:${VERSION}-arm64"
+            echo "docker_url=${IMAGE}:latest" >> $GITHUB_OUTPUT
+          else
+            docker buildx imagetools create \
+              -t "${IMAGE}:${STAGE}" \
+              "${IMAGE}:${VERSION}-amd64" \
+              "${IMAGE}:${VERSION}-arm64"
+            echo "docker_url=${IMAGE}:${STAGE}" >> $GITHUB_OUTPUT
+          fi
+
+  # Deployment summary
+  deploy-summary:
+    name: Deployment Summary
+    runs-on: ubuntu-latest
+    needs: [npm-publish, docker-manifest]
+    if: "!cancelled()"
+    outputs:
+      status: ${{ steps.summary.outputs.status }}
+      npm_url: ${{ steps.summary.outputs.npm_url }}
+      docker_url: ${{ steps.summary.outputs.docker_url }}
+    steps:
+      - name: Summarize deployment
+        id: summary
+        run: |
+          NPM_STATUS="${{ needs.npm-publish.outputs.status || 'skipped' }}"
+          NPM_URL="${{ needs.npm-publish.outputs.npm_url }}"
+          DOCKER_URL="${{ needs.docker-manifest.outputs.docker_url || '' }}"
+
+          echo "npm_url=$NPM_URL" >> $GITHUB_OUTPUT
+          echo "docker_url=$DOCKER_URL" >> $GITHUB_OUTPUT
+
+          if [ "$NPM_STATUS" = "success" ] || [ "$NPM_STATUS" = "skipped" ]; then
+            echo "status=success" >> $GITHUB_OUTPUT
+          else
+            echo "status=failed" >> $GITHUB_OUTPUT
+          fi
+
+          # Generate summary
+          echo "## Deployment Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Stage | ${{ inputs.deployment_stage }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Version | ${{ inputs.app_version }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| npm | $NPM_STATUS |" >> $GITHUB_STEP_SUMMARY
+          echo "| Docker | ${{ needs.docker-manifest.result || 'skipped' }} |" >> $GITHUB_STEP_SUMMARY
+
+  # Discord notification
+  notify:
+    name: Discord Notification
+    needs: deploy-summary
+    if: "!cancelled()"
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord success notification
+        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.deploy-summary.outputs.status == 'success' }}
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "🚀 Deployed: ${{ inputs.deployment_stage }} v${{ inputs.app_version }}"
+          description: |
+            **npm**: ${{ needs.deploy-summary.outputs.npm_url || 'skipped' }}
+            **Docker**: ${{ needs.deploy-summary.outputs.docker_url || 'skipped' }}
+          color: "3066993"
+
+      - name: Discord failure notification
+        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.deploy-summary.outputs.status != 'success' }}
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "❌ Deployment Failed: ${{ inputs.deployment_stage }}"
+          description: |
+            **Version**: ${{ inputs.app_version }}
+            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          color: "15158332"

.github/workflows/feature-pr.yml

@@ -0,0 +1,94 @@
+name: Feature PR
+
+# Auto-create PR from dev/* branches to develop
+# This is the entry point for new features into the staging pipeline
+
+on:
+  push:
+    branches:
+      - "dev/**"
+      - "feature/**"
+      - "fix/**"
+
+concurrency:
+  group: feature-pr-${{ github.ref_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  create-pr:
+    name: Create PR to develop
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Ensure develop branch exists
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if git ls-remote --heads origin develop | grep -q develop; then
+            echo "develop branch already exists"
+          else
+            echo "develop branch does not exist — creating from main"
+            git push origin origin/main:refs/heads/develop
+          fi
+
+      - name: Check for existing PR
+        id: check-pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ github.ref_name }}"
+          TARGET="develop"
+
+          # Check if PR already exists
+          EXISTING=$(gh pr list --head "$BRANCH" --base "$TARGET" --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
+            echo "PR #$EXISTING already exists for $BRANCH → $TARGET"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create PR
+        if: steps.check-pr.outputs.exists != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ github.ref_name }}"
+          TARGET="develop"
+
+          # Extract title from branch name (dev/foo-bar → foo bar)
+          TITLE=$(echo "$BRANCH" | sed 's|^dev/||; s|^feature/||; s|^fix/||; s|-| |g; s|_| |g')
+
+          # Capitalize first letter
+          TITLE="$(echo "${TITLE:0:1}" | tr '[:lower:]' '[:upper:]')${TITLE:1}"
+
+          # Create PR body
+          BODY=$(cat << 'PRBODY'
+          Auto-created PR from feature branch.
+
+          ## Changes
+
+          <!-- Describe your changes here -->
+
+          ---
+          *This PR was auto-created by the feature-pr workflow.*
+          PRBODY
+          )
+
+          gh pr create \
+            --base "$TARGET" \
+            --head "$BRANCH" \
+            --title "$TITLE" \
+            --body "$BODY"
+
+          echo "Created PR: $BRANCH → $TARGET"

.github/workflows/formal-conformance.yml

@@ -3,6 +3,10 @@ name: Formal models (informational conformance)
 on:
   pull_request:
 
+concurrency:
+  group: formal-conformance-${{ github.event.pull_request.number || github.ref_name }}
+  cancel-in-progress: true
+
 jobs:
   formal_conformance:
     runs-on: ubuntu-latest

.github/workflows/generate-changelog.yml

@@ -0,0 +1,129 @@
+name: Generate Changelog
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: "Version for the changelog"
+        required: true
+        type: string
+      release_type:
+        description: "Release type: alpha, beta, or stable"
+        required: true
+        type: string
+    outputs:
+      changelog:
+        description: "Generated changelog content"
+        value: ${{ jobs.generate.outputs.changelog }}
+      changelog_file:
+        description: "Path to changelog file"
+        value: ${{ jobs.generate.outputs.changelog_file }}
+
+jobs:
+  generate:
+    name: Generate Changelog
+    runs-on: ubuntu-latest
+    outputs:
+      changelog: ${{ steps.generate.outputs.changelog }}
+      changelog_file: ${{ steps.generate.outputs.changelog_file }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate changelog
+        id: generate
+        run: |
+          VERSION="${{ inputs.version }}"
+          RELEASE_TYPE="${{ inputs.release_type }}"
+          DATE=$(date +%Y-%m-%d)
+
+          # Start building changelog
+          CHANGELOG="## v${VERSION} (${DATE})\n\n"
+
+          # Initialize sections
+          FEATURES=""
+          FIXES=""
+          DOCS=""
+          CHORES=""
+          OTHER=""
+
+          # Get commits since last tag
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+
+          if [ -n "$LATEST_TAG" ]; then
+            COMMITS=$(git log ${LATEST_TAG}..HEAD --oneline --format="%s")
+          else
+            COMMITS=$(git log --oneline --format="%s" | head -50)
+          fi
+
+          # Categorize commits by conventional commit type
+          while IFS= read -r commit; do
+            if [ -z "$commit" ]; then
+              continue
+            fi
+            
+            # Extract type from conventional commit
+            if [[ "$commit" =~ ^feat(\(.+\))?:\ (.+)$ ]]; then
+              FEATURES="${FEATURES}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^fix(\(.+\))?:\ (.+)$ ]]; then
+              FIXES="${FIXES}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^docs(\(.+\))?:\ (.+)$ ]]; then
+              DOCS="${DOCS}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^chore(\(.+\))?:\ (.+)$ ]]; then
+              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^refactor(\(.+\))?:\ (.+)$ ]]; then
+              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^test(\(.+\))?:\ (.+)$ ]]; then
+              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
+            elif [[ "$commit" =~ ^ci(\(.+\))?:\ (.+)$ ]]; then
+              CHORES="${CHORES}- ${BASH_REMATCH[2]}\n"
+            else
+              # Non-conventional commit, add to other
+              OTHER="${OTHER}- ${commit}\n"
+            fi
+          done <<< "$COMMITS"
+
+          # Build final changelog
+          if [ -n "$FEATURES" ]; then
+            CHANGELOG="${CHANGELOG}### ✨ Features\n\n${FEATURES}\n"
+          fi
+
+          if [ -n "$FIXES" ]; then
+            CHANGELOG="${CHANGELOG}### 🐛 Bug Fixes\n\n${FIXES}\n"
+          fi
+
+          if [ -n "$DOCS" ]; then
+            CHANGELOG="${CHANGELOG}### 📚 Documentation\n\n${DOCS}\n"
+          fi
+
+          if [ -n "$CHORES" ]; then
+            CHANGELOG="${CHANGELOG}### 🔧 Maintenance\n\n${CHORES}\n"
+          fi
+
+          if [ -n "$OTHER" ]; then
+            CHANGELOG="${CHANGELOG}### Other Changes\n\n${OTHER}\n"
+          fi
+
+          # If no categorized commits, add a simple message
+          if [ -z "$FEATURES" ] && [ -z "$FIXES" ] && [ -z "$DOCS" ] && [ -z "$CHORES" ] && [ -z "$OTHER" ]; then
+            CHANGELOG="${CHANGELOG}No notable changes in this release.\n"
+          fi
+
+          # Add release metadata
+          CHANGELOG="${CHANGELOG}\n---\n\n"
+          CHANGELOG="${CHANGELOG}**Release Type**: ${RELEASE_TYPE}\n"
+          CHANGELOG="${CHANGELOG}**Full Changelog**: https://github.com/${{ github.repository }}/compare/${LATEST_TAG:-initial}...v${VERSION}\n"
+
+          # Escape for multiline output (random delimiter prevents collision with commit messages)
+          DELIMITER="CHANGELOG_$(openssl rand -hex 16)"
+          echo "changelog<<${DELIMITER}" >> $GITHUB_OUTPUT
+          echo -e "$CHANGELOG" >> $GITHUB_OUTPUT
+          echo "${DELIMITER}" >> $GITHUB_OUTPUT
+          echo "changelog_file=CHANGELOG.md" >> $GITHUB_OUTPUT
+
+          # Also write to step summary
+          echo "## Generated Changelog" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo -e "$CHANGELOG" >> $GITHUB_STEP_SUMMARY

.github/workflows/hotfix-pr.yml

@@ -0,0 +1,93 @@
+name: Hotfix PR
+
+# Emergency hotfix workflow - bypasses staging pipeline
+# Use for critical security fixes or production-breaking bugs only
+#
+# Flow: hotfix/* → main (directly, with expedited review)
+
+on:
+  push:
+    branches:
+      - "hotfix/**"
+
+concurrency:
+  group: hotfix-${{ github.ref_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  create-pr:
+    name: Create Hotfix PR
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for existing PR
+        id: check-pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ github.ref_name }}"
+
+          EXISTING=$(gh pr list --head "$BRANCH" --base main --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
+            echo "Hotfix PR #$EXISTING already exists"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Hotfix PR
+        if: steps.check-pr.outputs.exists != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="${{ github.ref_name }}"
+
+          # Extract title from branch name
+          TITLE=$(echo "$BRANCH" | sed 's|^hotfix/||; s|-| |g; s|_| |g')
+          TITLE="🚨 HOTFIX: $(echo "${TITLE:0:1}" | tr '[:lower:]' '[:upper:]')${TITLE:1}"
+
+          # Create PR body
+          BODY=$(cat << 'PRBODY'
+          ## 🚨 Emergency Hotfix
+
+          **This PR bypasses the normal staging pipeline.**
+
+          ### What's broken?
+          <!-- Describe the production issue -->
+
+          ### Root cause
+          <!-- Brief explanation of what went wrong -->
+
+          ### Fix
+          <!-- What this hotfix does -->
+
+          ### Verification
+          - [ ] Tested locally
+          - [ ] Reviewed by at least one other maintainer
+          - [ ] Post-merge monitoring plan in place
+
+          ---
+          ⚠️ **After merging:** Cherry-pick this fix to `develop`, `alpha`, and `beta` branches to keep them in sync.
+
+          *This PR was auto-created by the hotfix-pr workflow.*
+          PRBODY
+          )
+
+          gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "$TITLE" \
+            --label "hotfix,priority:critical" \
+            --body "$BODY"
+
+          echo "Created hotfix PR: $BRANCH → main"

.github/workflows/install-smoke.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
   workflow_dispatch:
 
+concurrency:
+  group: install-smoke-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
 jobs:
   install-smoke:
     runs-on: ubuntu-latest

.github/workflows/promote-branch.yml

@@ -0,0 +1,319 @@
+name: Promote Branch
+
+# Staged branch promotion for openclaw:
+#
+# develop → alpha → beta → main
+#
+# - External contributors: target `develop`
+# - develop → alpha: auto-creates PR after core checks pass
+# - alpha → beta: auto-creates PR after alpha tests pass (+ secrets scan)
+# - beta → main: auto-creates PR after full tests pass (+ Windows)
+#
+# Merging to main triggers a release (handled separately by release workflow)
+
+on:
+  push:
+    branches:
+      - develop
+      - alpha
+      - beta
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+  workflow_dispatch:
+    inputs:
+      source_branch:
+        description: "Source branch to promote from"
+        required: true
+        type: choice
+        options:
+          - develop
+          - alpha
+          - beta
+      skip_tests:
+        description: "Skip tests (use with caution)"
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: promote-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  # Determine promotion target
+  determine-target:
+    name: Determine Target Branch
+    runs-on: ubuntu-latest
+    outputs:
+      source: ${{ steps.determine.outputs.source }}
+      target: ${{ steps.determine.outputs.target }}
+      test_stage: ${{ steps.determine.outputs.test_stage }}
+      should_promote: ${{ steps.determine.outputs.should_promote }}
+    steps:
+      - name: Determine promotion target
+        id: determine
+        run: |
+          # Get source branch
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            SOURCE="${{ inputs.source_branch }}"
+          else
+            SOURCE="${{ github.ref_name }}"
+          fi
+
+          echo "source=$SOURCE" >> $GITHUB_OUTPUT
+
+          case "$SOURCE" in
+            develop)
+              echo "target=alpha" >> $GITHUB_OUTPUT
+              echo "test_stage=develop" >> $GITHUB_OUTPUT
+              echo "should_promote=true" >> $GITHUB_OUTPUT
+              ;;
+            alpha)
+              echo "target=beta" >> $GITHUB_OUTPUT
+              echo "test_stage=alpha" >> $GITHUB_OUTPUT
+              echo "should_promote=true" >> $GITHUB_OUTPUT
+              ;;
+            beta)
+              echo "target=main" >> $GITHUB_OUTPUT
+              echo "test_stage=beta" >> $GITHUB_OUTPUT
+              echo "should_promote=true" >> $GITHUB_OUTPUT
+              ;;
+            *)
+              echo "target=" >> $GITHUB_OUTPUT
+              echo "test_stage=" >> $GITHUB_OUTPUT
+              echo "should_promote=false" >> $GITHUB_OUTPUT
+              ;;
+          esac
+
+  # Ensure target branch exists (create from main if not)
+  ensure-target-branch:
+    name: Ensure Target Branch
+    needs: determine-target
+    if: needs.determine-target.outputs.should_promote == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create target branch if missing
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TARGET="${{ needs.determine-target.outputs.target }}"
+
+          if git ls-remote --exit-code origin "refs/heads/$TARGET" >/dev/null 2>&1; then
+            echo "Branch '$TARGET' already exists"
+          else
+            echo "Branch '$TARGET' does not exist — creating from main"
+            git push origin "origin/main:refs/heads/$TARGET"
+          fi
+
+  # Run stage-appropriate tests
+  run-tests:
+    name: Run Tests
+    needs: [determine-target, ensure-target-branch]
+    if: ${{ needs.determine-target.outputs.should_promote == 'true' && (github.event_name != 'workflow_dispatch' || !inputs.skip_tests) }}
+    uses: ./.github/workflows/testing-strategy.yml
+    with:
+      test_stage: ${{ needs.determine-target.outputs.test_stage }}
+      app_version: ${{ github.sha }}
+    secrets: inherit
+
+  # Create promotion PR
+  create-promotion-pr:
+    name: Create Promotion PR
+    needs: [determine-target, ensure-target-branch, run-tests]
+    if: |
+      !cancelled() &&
+      needs.determine-target.outputs.should_promote == 'true' &&
+      (needs.run-tests.outputs.test_status == 'passed' || (github.event_name == 'workflow_dispatch' && inputs.skip_tests))
+    runs-on: ubuntu-latest
+    outputs:
+      pr_number: ${{ steps.output-pr.outputs.pull-request-number }}
+      pr_url: ${{ steps.output-pr.outputs.pull-request-url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.determine-target.outputs.source }}
+          fetch-depth: 0
+
+      - name: Get commit info
+        id: commits
+        run: |
+          TARGET="${{ needs.determine-target.outputs.target }}"
+
+          # Fetch target branch
+          git fetch origin $TARGET 2>/dev/null || true
+
+          # Get commits not in target
+          if git rev-parse origin/$TARGET >/dev/null 2>&1; then
+            COMMIT_COUNT=$(git rev-list --count origin/$TARGET..HEAD 2>/dev/null || echo "0")
+            COMMIT_SUMMARY=$(git log origin/$TARGET..HEAD --oneline --format="- %s (%h)" 2>/dev/null | head -20 || echo "Initial promotion")
+          else
+            COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+            COMMIT_SUMMARY=$(git log --oneline --format="- %s (%h)" 2>/dev/null | head -20 || echo "Initial promotion")
+          fi
+
+          echo "count=$COMMIT_COUNT" >> $GITHUB_OUTPUT
+          DELIM="COMMITS_$(openssl rand -hex 16)"
+          echo "summary<<${DELIM}" >> $GITHUB_OUTPUT
+          echo "$COMMIT_SUMMARY" >> $GITHUB_OUTPUT
+          echo "${DELIM}" >> $GITHUB_OUTPUT
+
+      - name: Check for existing PR
+        id: check-pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          SOURCE="${{ needs.determine-target.outputs.source }}"
+          TARGET="${{ needs.determine-target.outputs.target }}"
+
+          EXISTING=$(gh pr list --head "$SOURCE" --base "$TARGET" --json number --jq '.[0].number // empty')
+
+          if [ -n "$EXISTING" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT
+            echo "pr_url=https://github.com/${{ github.repository }}/pull/$EXISTING" >> $GITHUB_OUTPUT
+            echo "Promotion PR #$EXISTING already exists for $SOURCE → $TARGET"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Pull Request
+        id: create-pr
+        if: steps.check-pr.outputs.exists != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          SOURCE="${{ needs.determine-target.outputs.source }}"
+          TARGET="${{ needs.determine-target.outputs.target }}"
+          TEST_STAGE="${{ needs.determine-target.outputs.test_stage }}"
+          COMMIT_COUNT="${{ steps.commits.outputs.count }}"
+
+          # Write PR body to a temp file to avoid shell quoting issues
+          BODY_FILE=$(mktemp)
+          cat > "$BODY_FILE" <<__PRBODY__
+          ## Staged Promotion
+
+          | Property | Value |
+          |----------|-------|
+          | Source | \`${SOURCE}\` |
+          | Target | \`${TARGET}\` |
+          | Test Stage | \`${TEST_STAGE}\` |
+
+          ### Changes (${COMMIT_COUNT} commits)
+
+          ${{ steps.commits.outputs.summary }}
+
+          ### Checklist
+
+          - [ ] Changes reviewed
+          - [ ] CI passing
+          - [ ] Ready to promote
+
+          ---
+          *Auto-generated by the branch promotion workflow.*
+          __PRBODY__
+
+          PR_URL=$(gh pr create \
+            --base "$TARGET" \
+            --head "$SOURCE" \
+            --title "🚀 Promote: $SOURCE → $TARGET" \
+            --body-file "$BODY_FILE" \
+            --label "promotion")
+
+          rm -f "$BODY_FILE"
+
+          PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')
+
+          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
+          echo "pr_url=$PR_URL" >> $GITHUB_OUTPUT
+          echo "Created promotion PR: $SOURCE → $TARGET"
+
+      - name: Output existing PR
+        id: output-pr
+        run: |
+          if [ "${{ steps.check-pr.outputs.exists }}" = "true" ]; then
+            echo "pull-request-number=${{ steps.check-pr.outputs.pr_number }}" >> $GITHUB_OUTPUT
+            echo "pull-request-url=${{ steps.check-pr.outputs.pr_url }}" >> $GITHUB_OUTPUT
+          else
+            echo "pull-request-number=${{ steps.create-pr.outputs.pr_number }}" >> $GITHUB_OUTPUT
+            echo "pull-request-url=${{ steps.create-pr.outputs.pr_url }}" >> $GITHUB_OUTPUT
+          fi
+
+  # Auto-merge for develop → alpha (fast-track, new PRs only)
+  auto-merge:
+    name: Auto-merge (develop → alpha)
+    needs: [determine-target, create-promotion-pr]
+    if: |
+      needs.determine-target.outputs.source == 'develop' &&
+      needs.create-promotion-pr.outputs.pr_number != '' &&
+      needs.create-promotion-pr.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge
+        run: |
+          gh pr merge ${{ needs.create-promotion-pr.outputs.pr_number }} \
+            --auto \
+            --squash \
+            --repo ${{ github.repository }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Notify about promotion
+  notify-promotion:
+    name: Notify Promotion
+    needs: [determine-target, create-promotion-pr]
+    if: "!cancelled() && needs.create-promotion-pr.outputs.pr_url != ''"
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord notification
+        if: env.DISCORD_WEBHOOK_URL != ''
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "🔄 Promotion PR: ${{ needs.determine-target.outputs.source }} → ${{ needs.determine-target.outputs.target }}"
+          description: |
+            **PR**: ${{ needs.create-promotion-pr.outputs.pr_url }}
+            **Stage**: ${{ needs.determine-target.outputs.test_stage }}
+          color: "3447003"
+
+  # Handle failed tests
+  notify-failure:
+    name: Notify Test Failure
+    needs: [determine-target, run-tests]
+    if: |
+      !cancelled() &&
+      needs.run-tests.outputs.test_status != 'passed' &&
+      !inputs.skip_tests
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord notification
+        if: env.DISCORD_WEBHOOK_URL != ''
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "❌ Promotion Blocked: ${{ needs.determine-target.outputs.source }}"
+          description: |
+            **Target**: ${{ needs.determine-target.outputs.target }}
+            **Reason**: Tests failed
+            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          color: "15158332"

.github/workflows/release-orchestrator.yml

@@ -0,0 +1,264 @@
+name: Release Orchestrator
+
+# Orchestrates staged releases for openclaw
+#
+# This workflow is called when code is promoted to main (stable release)
+# or can be triggered manually for alpha/beta releases from their branches.
+#
+# Flow: version → changelog → test → deploy → release
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+      - ".github/workflows/docs-*.yml"
+
+  workflow_call:
+    inputs:
+      release_type:
+        description: "Release type: alpha, beta, or stable"
+        required: true
+        type: string
+      source_branch:
+        description: "Source branch for the release"
+        required: true
+        type: string
+      dry_run:
+        description: "Perform a dry run without publishing"
+        required: false
+        type: boolean
+        default: false
+    outputs:
+      version:
+        description: "The released version"
+        value: ${{ jobs.version.outputs.new_version }}
+      release_url:
+        description: "URL to the GitHub release"
+        value: ${{ jobs.release.outputs.release_url }}
+      status:
+        description: "Release status"
+        value: ${{ jobs.release.outputs.status }}
+    secrets:
+      NPM_TOKEN:
+        required: false
+      DISCORD_WEBHOOK_URL:
+        required: false
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  # Determine release parameters (push vs workflow_call)
+  determine-params:
+    name: Determine Parameters
+    runs-on: ubuntu-latest
+    outputs:
+      release_type: ${{ steps.params.outputs.release_type }}
+      source_branch: ${{ steps.params.outputs.source_branch }}
+      dry_run: ${{ steps.params.outputs.dry_run }}
+    steps:
+      - name: Set parameters
+        id: params
+        run: |
+          # When triggered by push to main, use stable defaults
+          if [ "${{ github.event_name }}" = "push" ]; then
+            echo "release_type=stable" >> $GITHUB_OUTPUT
+            echo "source_branch=main" >> $GITHUB_OUTPUT
+            echo "dry_run=false" >> $GITHUB_OUTPUT
+          else
+            # workflow_call - use provided inputs
+            echo "release_type=${{ inputs.release_type }}" >> $GITHUB_OUTPUT
+            echo "source_branch=${{ inputs.source_branch }}" >> $GITHUB_OUTPUT
+            echo "dry_run=${{ inputs.dry_run }}" >> $GITHUB_OUTPUT
+          fi
+
+  # Get commits since last release
+  get-commits:
+    name: Get Commits
+    needs: determine-params
+    runs-on: ubuntu-latest
+    outputs:
+      commits: ${{ steps.commits.outputs.commits }}
+      has_changes: ${{ steps.commits.outputs.has_changes }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.determine-params.outputs.source_branch }}
+
+      - name: Get commits since last tag
+        id: commits
+        run: |
+          # Get latest tag for this release type
+          case "${{ needs.determine-params.outputs.release_type }}" in
+            alpha)
+              PATTERN="v*-alpha.*"
+              ;;
+            beta)
+              PATTERN="v*-beta.*"
+              ;;
+            stable)
+              PATTERN="v[0-9]*.[0-9]*.[0-9]*"
+              ;;
+          esac
+
+          # Filter out prerelease tags for stable (glob * matches -alpha/-beta suffixes)
+          if [ "${{ needs.determine-params.outputs.release_type }}" = "stable" ]; then
+            LATEST_TAG=$(git tag -l "$PATTERN" --sort=-v:refname | grep -v -E '-(alpha|beta)\.' | head -1)
+          else
+            LATEST_TAG=$(git tag -l "$PATTERN" --sort=-v:refname | head -1)
+          fi
+
+          if [ -z "$LATEST_TAG" ]; then
+            # No previous tag, use all commits
+            LATEST_TAG=$(git rev-list --max-parents=0 HEAD)
+            echo "No previous ${{ needs.determine-params.outputs.release_type }} tag found, using initial commit"
+          else
+            echo "Latest ${{ needs.determine-params.outputs.release_type }} tag: $LATEST_TAG"
+          fi
+
+          COMMITS=$(git log ${LATEST_TAG}..HEAD --oneline --format="- %s (%h)")
+
+          if [ -z "$COMMITS" ]; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "commits=" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            DELIM="COMMITS_$(openssl rand -hex 16)"
+            echo "commits<<${DELIM}" >> $GITHUB_OUTPUT
+            echo "$COMMITS" >> $GITHUB_OUTPUT
+            echo "${DELIM}" >> $GITHUB_OUTPUT
+          fi
+
+  # Version operations
+  version:
+    name: Version
+    needs: [determine-params, get-commits]
+    if: needs.get-commits.outputs.has_changes == 'true'
+    uses: ./.github/workflows/version-operations.yml
+    with:
+      release_type: ${{ needs.determine-params.outputs.release_type }}
+      source_branch: ${{ needs.determine-params.outputs.source_branch }}
+      should_bump: true
+      dry_run: ${{ needs.determine-params.outputs.dry_run }}
+
+  # Generate changelog
+  changelog:
+    name: Changelog
+    needs: [determine-params, get-commits, version]
+    if: needs.get-commits.outputs.has_changes == 'true'
+    uses: ./.github/workflows/generate-changelog.yml
+    with:
+      version: ${{ needs.version.outputs.new_version }}
+      release_type: ${{ needs.determine-params.outputs.release_type }}
+
+  # Run full test suite for the release type
+  test:
+    name: Test
+    needs: [determine-params, get-commits, version]
+    if: needs.get-commits.outputs.has_changes == 'true'
+    uses: ./.github/workflows/testing-strategy.yml
+    with:
+      test_stage: ${{ needs.determine-params.outputs.release_type }}
+      app_version: ${{ needs.version.outputs.new_version }}
+    secrets: inherit
+
+  # Deploy (npm + Docker)
+  deploy:
+    name: Deploy
+    needs: [determine-params, version, test]
+    if: ${{ needs.determine-params.outputs.dry_run != 'true' && needs.test.outputs.test_status == 'passed' }}
+    uses: ./.github/workflows/deployment-strategy.yml
+    with:
+      deployment_stage: ${{ needs.determine-params.outputs.release_type }}
+      app_version: ${{ needs.version.outputs.new_version }}
+      source_branch: ${{ needs.determine-params.outputs.source_branch }}
+    secrets: inherit
+
+  # Create GitHub release
+  release:
+    name: GitHub Release
+    needs: [determine-params, version, changelog, deploy]
+    if: ${{ needs.determine-params.outputs.dry_run != 'true' }}
+    runs-on: ubuntu-latest
+    outputs:
+      release_url: ${{ steps.create-release.outputs.html_url }}
+      status: ${{ steps.status.outputs.status }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.determine-params.outputs.source_branch }}
+
+      - name: Create GitHub Release
+        id: create-release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ needs.version.outputs.new_version }}
+          name: openclaw ${{ needs.version.outputs.new_version }}
+          body: ${{ needs.changelog.outputs.changelog }}
+          prerelease: ${{ needs.determine-params.outputs.release_type != 'stable' }}
+          draft: false
+
+      - name: Set status
+        id: status
+        run: echo "status=success" >> $GITHUB_OUTPUT
+
+  # Notify on success
+  notify-success:
+    name: Notify Success
+    needs: [determine-params, version, release]
+    if: ${{ !cancelled() && needs.release.result == 'success' }}
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord notification
+        if: env.DISCORD_WEBHOOK_URL != ''
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "🎉 Released: openclaw v${{ needs.version.outputs.new_version }}"
+          description: |
+            **Type**: ${{ needs.determine-params.outputs.release_type }}
+            **Release**: ${{ needs.release.outputs.release_url }}
+          color: "3066993"
+
+  # Notify on failure
+  notify-failure:
+    name: Notify Failure
+    needs: [determine-params, version, test, deploy, release]
+    if: |
+      !cancelled() &&
+      needs.version.result != 'skipped' &&
+      (needs.test.result == 'failure' || needs.deploy.result == 'failure' || needs.release.result == 'failure')
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord notification
+        if: env.DISCORD_WEBHOOK_URL != ''
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "❌ Release Failed: ${{ needs.determine-params.outputs.release_type }}"
+          description: |
+            **Branch**: ${{ needs.determine-params.outputs.source_branch }}
+            **Tests**: ${{ needs.test.outputs.test_status }}
+            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          color: "15158332"

.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+# Manual release workflow - triggers the release orchestrator
+#
+# Branch → Release Type mapping:
+#   alpha  → releases from 'alpha' branch with -alpha.N suffix
+#   beta   → releases from 'beta' branch with -beta.N suffix
+#   stable → releases from 'main' branch with YYYY.M.D version
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: "Release type"
+        required: true
+        type: choice
+        options:
+          - alpha
+          - beta
+          - stable
+        default: "alpha"
+      dry_run:
+        description: "Dry run (no publish)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  determine-branch:
+    runs-on: ubuntu-latest
+    outputs:
+      branch: ${{ steps.branch.outputs.name }}
+    steps:
+      - name: Determine source branch
+        id: branch
+        run: |
+          case "${{ inputs.release_type }}" in
+            alpha)  echo "name=alpha" >> $GITHUB_OUTPUT ;;
+            beta)   echo "name=beta" >> $GITHUB_OUTPUT ;;
+            stable) echo "name=main" >> $GITHUB_OUTPUT ;;
+          esac
+
+  release:
+    name: Release
+    needs: determine-branch
+    uses: ./.github/workflows/release-orchestrator.yml
+    with:
+      release_type: ${{ inputs.release_type }}
+      source_branch: ${{ needs.determine-branch.outputs.branch }}
+      dry_run: ${{ inputs.dry_run }}
+    secrets: inherit

.github/workflows/rollback.yml

@@ -0,0 +1,256 @@
+name: Rollback
+
+# Emergency rollback workflow
+#
+# Reverts npm + Docker to a previous known-good version.
+# Does NOT revert git — the bad commits stay in history.
+# Create a hotfix branch to fix forward after rolling back.
+#
+# What it does:
+#   1. Re-tags the previous version as @latest / :latest on npm + Docker
+#   2. Creates a GitHub release noting the rollback
+#   3. Notifies Discord
+#
+# What it does NOT do:
+#   - Revert git commits (fix forward instead)
+#   - Remove the bad version from npm (use `npm unpublish` manually if needed)
+
+on:
+  workflow_dispatch:
+    inputs:
+      rollback_to:
+        description: "Version to roll back to (e.g. 2026.2.5)"
+        required: true
+        type: string
+      reason:
+        description: "Reason for rollback"
+        required: true
+        type: string
+      rollback_npm:
+        description: "Roll back npm dist-tag"
+        required: false
+        type: boolean
+        default: true
+      rollback_docker:
+        description: "Roll back Docker :latest tag"
+        required: false
+        type: boolean
+        default: true
+
+concurrency:
+  group: rollback
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  # Validate the target version exists
+  validate:
+    name: Validate Target Version
+    runs-on: ubuntu-latest
+    outputs:
+      tag_exists: ${{ steps.check.outputs.tag_exists }}
+      npm_exists: ${{ steps.check.outputs.npm_exists }}
+      docker_exists: ${{ steps.check.outputs.docker_exists }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate version
+        id: check
+        run: |
+          VERSION="${{ inputs.rollback_to }}"
+
+          # Check git tag
+          if git tag -l "v${VERSION}" | grep -q .; then
+            echo "tag_exists=true" >> $GITHUB_OUTPUT
+            echo "✅ Git tag v${VERSION} exists"
+          else
+            echo "tag_exists=false" >> $GITHUB_OUTPUT
+            echo "❌ Git tag v${VERSION} not found"
+          fi
+
+          # Check npm
+          if npm view "openclaw@${VERSION}" version 2>/dev/null | grep -q "${VERSION}"; then
+            echo "npm_exists=true" >> $GITHUB_OUTPUT
+            echo "✅ npm version ${VERSION} exists"
+          else
+            echo "npm_exists=false" >> $GITHUB_OUTPUT
+            echo "⚠️ npm version ${VERSION} not found (npm rollback will be skipped)"
+          fi
+
+          # Check Docker
+          if docker manifest inspect "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${VERSION}" >/dev/null 2>&1; then
+            echo "docker_exists=true" >> $GITHUB_OUTPUT
+            echo "✅ Docker image ${VERSION} exists"
+          else
+            echo "docker_exists=false" >> $GITHUB_OUTPUT
+            echo "⚠️ Docker image ${VERSION} not found (Docker rollback will be skipped)"
+          fi
+
+      - name: Fail if tag doesn't exist
+        if: steps.check.outputs.tag_exists != 'true'
+        run: |
+          echo "::error::Version v${{ inputs.rollback_to }} does not exist as a git tag"
+          exit 1
+
+  # Roll back npm dist-tag
+  rollback-npm:
+    name: Rollback npm
+    needs: validate
+    if: ${{ inputs.rollback_npm && needs.validate.outputs.npm_exists == 'true' }}
+    runs-on: ubuntu-latest
+    outputs:
+      status: ${{ steps.rollback.outputs.status }}
+    steps:
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Roll back npm @latest tag
+        id: rollback
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          VERSION="${{ inputs.rollback_to }}"
+
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "::warning::NPM_TOKEN not set, skipping npm rollback"
+            echo "status=skipped" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Move the @latest dist-tag to the rollback version
+          if npm dist-tag add "openclaw@${VERSION}" latest; then
+            echo "status=success" >> $GITHUB_OUTPUT
+            echo "✅ npm @latest now points to ${VERSION}"
+
+            # Show current dist-tags for verification
+            npm dist-tag ls openclaw
+          else
+            echo "status=failed" >> $GITHUB_OUTPUT
+            echo "::error::Failed to update npm dist-tag"
+            exit 1
+          fi
+
+  # Roll back Docker :latest tag
+  rollback-docker:
+    name: Rollback Docker
+    needs: validate
+    if: ${{ inputs.rollback_docker && needs.validate.outputs.docker_exists == 'true' }}
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      status: ${{ steps.rollback.outputs.status }}
+    steps:
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Roll back Docker :latest tag
+        id: rollback
+        run: |
+          VERSION="${{ inputs.rollback_to }}"
+          IMAGE="${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}"
+
+          # Re-tag the rollback version as :latest
+          if docker buildx imagetools create -t "${IMAGE}:latest" "${IMAGE}:${VERSION}"; then
+            echo "status=success" >> $GITHUB_OUTPUT
+            echo "✅ Docker :latest now points to ${VERSION}"
+          else
+            echo "status=failed" >> $GITHUB_OUTPUT
+            echo "::error::Failed to retag Docker image"
+            exit 1
+          fi
+
+  # Create rollback release note
+  create-rollback-release:
+    name: Create Rollback Release
+    needs: [validate, rollback-npm, rollback-docker]
+    if: "!cancelled() && needs.validate.result == 'success'"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get current version
+        id: current
+        run: |
+          CURRENT=$(node -p "require('./package.json').version")
+          echo "version=$CURRENT" >> $GITHUB_OUTPUT
+
+      - name: Create rollback release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ inputs.rollback_to }}
+          name: "⚠️ Rollback to openclaw ${{ inputs.rollback_to }}"
+          body: |
+            ## ⚠️ Rollback
+
+            | Property | Value |
+            |----------|-------|
+            | Rolled back from | `${{ steps.current.outputs.version }}` |
+            | Rolled back to | `${{ inputs.rollback_to }}` |
+            | Initiated by | @${{ github.actor }} |
+
+            ### Reason
+
+            ${{ inputs.reason }}
+
+            ### Rollback Status
+
+            | Target | Status |
+            |--------|--------|
+            | npm @latest | ${{ needs.rollback-npm.outputs.status || 'skipped' }} |
+            | Docker :latest | ${{ needs.rollback-docker.outputs.status || 'skipped' }} |
+
+            ### Next Steps
+
+            1. Investigate the issue in the rolled-back version
+            2. Create a `hotfix/*` branch with the fix
+            3. Merge via the hotfix workflow to restore forward progress
+
+            ---
+            *This release was created by the rollback workflow.*
+          make_latest: false
+          prerelease: false
+
+  # Notify
+  notify:
+    name: Discord Notification
+    needs: [validate, rollback-npm, rollback-docker, create-rollback-release]
+    if: "!cancelled() && needs.validate.result == 'success'"
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord notification
+        if: env.DISCORD_WEBHOOK_URL != ''
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "⚠️ ROLLBACK: openclaw → v${{ inputs.rollback_to }}"
+          description: |
+            **Reason**: ${{ inputs.reason }}
+            **Initiated by**: @${{ github.actor }}
+            **npm**: ${{ needs.rollback-npm.outputs.status || 'skipped' }}
+            **Docker**: ${{ needs.rollback-docker.outputs.status || 'skipped' }}
+          color: "15105570"

.github/workflows/testing-strategy.yml

@@ -0,0 +1,153 @@
+name: Testing Strategy
+
+# Reusable testing workflow for staged releases
+# Passes test_stage to ci.yml to control which platform tests run
+#
+# Progressive test coverage by stage:
+# - develop/alpha: core checks + secrets + android
+# - beta: + Windows tests
+# - stable: + macOS tests, macOS app, install smoke
+
+on:
+  workflow_call:
+    inputs:
+      test_stage:
+        description: "Testing stage: develop, alpha, beta, or stable"
+        required: true
+        type: string
+      app_version:
+        description: "Version of the application being tested"
+        required: false
+        type: string
+        default: "dev"
+    outputs:
+      test_status:
+        description: "Overall test status"
+        value: ${{ jobs.test-summary.outputs.overall_status }}
+    secrets:
+      DISCORD_WEBHOOK_URL:
+        required: false
+
+jobs:
+  # Run CI with stage-appropriate platform gates
+  ci:
+    name: Core CI
+    uses: ./.github/workflows/ci.yml
+    with:
+      test_stage: ${{ inputs.test_stage }}
+    secrets: inherit
+
+  # Install smoke test (stable only)
+  install-smoke:
+    name: Install Smoke Test
+    if: inputs.test_stage == 'stable'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - 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: Install pnpm deps (minimal)
+        run: pnpm install --ignore-scripts --frozen-lockfile
+
+      - name: Run installer smoke tests
+        env:
+          CLAWDBOT_INSTALL_URL: https://openclaw.ai/install.sh
+          CLAWDBOT_INSTALL_CLI_URL: https://openclaw.ai/install-cli.sh
+          CLAWDBOT_NO_ONBOARD: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_CLI: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_NONROOT: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_PREVIOUS: "1"
+        run: pnpm test:install:smoke
+
+  # Test summary
+  test-summary:
+    name: Test Summary (${{ inputs.test_stage }})
+    runs-on: ubuntu-latest
+    needs: [ci, install-smoke]
+    if: "!cancelled()"
+    outputs:
+      overall_status: ${{ steps.summary.outputs.overall_status }}
+    steps:
+      - name: Generate summary
+        id: summary
+        run: |
+          echo "## 🧪 Test Results - ${{ inputs.test_stage }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Test Suite | Result |" >> $GITHUB_STEP_SUMMARY
+          echo "|------------|--------|" >> $GITHUB_STEP_SUMMARY
+          echo "| CI (checks + secrets) | ${{ needs.ci.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Install Smoke | ${{ needs.install-smoke.result || 'skipped' }} |" >> $GITHUB_STEP_SUMMARY
+
+          # CI must pass (includes platform-specific jobs based on test_stage)
+          if [ "${{ needs.ci.result }}" != "success" ]; then
+            echo "overall_status=failed" >> $GITHUB_OUTPUT
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### ❌ CI failed" >> $GITHUB_STEP_SUMMARY
+            exit 0
+          fi
+
+          # Stage-specific checks
+          STAGE="${{ inputs.test_stage }}"
+          FAILED=false
+
+          if [ "$STAGE" = "stable" ]; then
+            if [ "${{ needs.install-smoke.result }}" = "failure" ]; then
+              FAILED=true
+            fi
+          fi
+
+          if [ "$FAILED" = "true" ]; then
+            echo "overall_status=failed" >> $GITHUB_OUTPUT
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### ❌ Some stage-specific tests failed" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "overall_status=passed" >> $GITHUB_OUTPUT
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### ✅ All required tests passed!" >> $GITHUB_STEP_SUMMARY
+          fi
+
+  # Discord notifications
+  notify:
+    name: Discord Notification
+    needs: test-summary
+    if: "!cancelled()"
+    runs-on: ubuntu-latest
+    env:
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Discord success notification
+        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.test-summary.outputs.overall_status == 'passed' }}
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "✅ Tests Passed: ${{ inputs.test_stage }} v${{ inputs.app_version }}"
+          description: "All tests passed for ${{ inputs.test_stage }} stage!"
+          color: "3066993"
+
+      - name: Discord failure notification
+        if: ${{ env.DISCORD_WEBHOOK_URL != '' && needs.test-summary.outputs.overall_status != 'passed' }}
+        uses: ./.github/actions/discord-notify
+        with:
+          webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+          title: "❌ Tests Failed: ${{ inputs.test_stage }} v${{ inputs.app_version }}"
+          description: |
+            Some tests failed for ${{ inputs.test_stage }} stage.
+            [View Logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          color: "15158332"

.github/workflows/version-operations.yml

@@ -0,0 +1,188 @@
+name: Version Operations
+
+# Version bump workflow for openclaw
+#
+# Version format: YYYY.M.D (stable) or YYYY.M.D-{alpha,beta}.N (prerelease)
+# Examples: 2026.2.6, 2026.2.6-alpha.1, 2026.2.6-beta.3
+
+on:
+  workflow_call:
+    inputs:
+      release_type:
+        description: "Release type: alpha, beta, or stable"
+        required: true
+        type: string
+      source_branch:
+        description: "Source branch"
+        required: true
+        type: string
+      should_bump:
+        description: "Whether to bump the version"
+        required: false
+        type: boolean
+        default: true
+      dry_run:
+        description: "Perform a dry run without committing"
+        required: false
+        type: boolean
+        default: false
+    outputs:
+      current_version:
+        description: "Current version before bump"
+        value: ${{ jobs.version.outputs.current_version }}
+      new_version:
+        description: "New version after bump"
+        value: ${{ jobs.version.outputs.new_version }}
+      version_tag:
+        description: "Version tag (with v prefix)"
+        value: ${{ jobs.version.outputs.version_tag }}
+
+permissions:
+  contents: write
+
+jobs:
+  version:
+    name: Version Operations
+    runs-on: ubuntu-latest
+    outputs:
+      current_version: ${{ steps.get-version.outputs.current }}
+      new_version: ${{ steps.bump-version.outputs.new }}
+      version_tag: ${{ steps.bump-version.outputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.source_branch }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+
+      - name: Get current version
+        id: get-version
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          echo "current=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          echo "Current version: $CURRENT_VERSION"
+
+      - name: Calculate new version
+        id: bump-version
+        run: |
+          CURRENT="${{ steps.get-version.outputs.current }}"
+          RELEASE_TYPE="${{ inputs.release_type }}"
+
+          # Get current date components
+          YEAR=$(date +%Y)
+          MONTH=$(date +%-m)
+          DAY=$(date +%-d)
+          TODAY="${YEAR}.${MONTH}.${DAY}"
+
+          # Parse current version to check if it's today + same type
+          # Patterns: YYYY.M.D or YYYY.M.D-type.N
+          if [[ "$CURRENT" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)(-([a-z]+)\.([0-9]+))?$ ]]; then
+            CURR_DATE="${BASH_REMATCH[1]}.${BASH_REMATCH[2]}.${BASH_REMATCH[3]}"
+            CURR_TYPE="${BASH_REMATCH[5]}"
+            CURR_NUM="${BASH_REMATCH[6]:-0}"
+          else
+            CURR_DATE=""
+            CURR_TYPE=""
+            CURR_NUM=0
+          fi
+
+          case "$RELEASE_TYPE" in
+            alpha)
+              if [ "$CURR_DATE" = "$TODAY" ] && [ "$CURR_TYPE" = "alpha" ]; then
+                # Same day, same type - increment prerelease number
+                NEW_NUM=$((CURR_NUM + 1))
+              else
+                # New day or different type - start at 1
+                NEW_NUM=1
+              fi
+              NEW_VERSION="${TODAY}-alpha.${NEW_NUM}"
+              ;;
+            beta)
+              if [ "$CURR_DATE" = "$TODAY" ] && [ "$CURR_TYPE" = "beta" ]; then
+                NEW_NUM=$((CURR_NUM + 1))
+              else
+                NEW_NUM=1
+              fi
+              NEW_VERSION="${TODAY}-beta.${NEW_NUM}"
+              ;;
+            stable)
+              # Stable releases use date; append counter if tag already exists
+              if git tag -l "v${TODAY}" | grep -q .; then
+                # Tag exists, find next available counter
+                COUNTER=1
+                while git tag -l "v${TODAY}.${COUNTER}" | grep -q .; do
+                  COUNTER=$((COUNTER + 1))
+                done
+                NEW_VERSION="${TODAY}.${COUNTER}"
+              else
+                NEW_VERSION="${TODAY}"
+              fi
+              ;;
+            *)
+              echo "Unknown release type: $RELEASE_TYPE"
+              exit 1
+              ;;
+          esac
+
+          echo "new=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "New version: $NEW_VERSION"
+
+      - name: Update package.json
+        if: ${{ inputs.should_bump && !inputs.dry_run }}
+        run: |
+          NEW_VERSION="${{ steps.bump-version.outputs.new }}"
+
+          # Update package.json version
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+            pkg.version = '$NEW_VERSION';
+            fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+          "
+
+          echo "Updated package.json to version $NEW_VERSION"
+
+      - name: Sync extension versions
+        if: ${{ inputs.should_bump && !inputs.dry_run }}
+        run: |
+          # Run plugins:sync if available (aligns extension package versions)
+          if npm run --silent plugins:sync 2>/dev/null; then
+            echo "Extension versions synced"
+          else
+            echo "plugins:sync not available, skipping"
+          fi
+
+      - name: Commit version bump
+        if: ${{ inputs.should_bump && !inputs.dry_run }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          NEW_VERSION="${{ steps.bump-version.outputs.new }}"
+
+          # Stage all version-related changes
+          git add package.json
+          git add extensions/*/package.json 2>/dev/null || true
+
+          # Check if there are changes to commit
+          if git diff --cached --quiet; then
+            echo "No version changes to commit"
+          else
+            git commit -m "chore: bump version to $NEW_VERSION"
+            git push origin ${{ inputs.source_branch }}
+          fi
+
+      - name: Create tag
+        if: ${{ inputs.should_bump && !inputs.dry_run }}
+        run: |
+          TAG="${{ steps.bump-version.outputs.tag }}"
+
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"

.github/workflows/workflow-sanity.yml

@@ -3,6 +3,11 @@ name: Workflow Sanity
 on:
   pull_request:
   push:
+    branches: [main]
+
+concurrency:
+  group: workflow-sanity-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
 
 jobs:
   no-tabs:

.markdownlint-cli2.jsonc

@@ -1,16 +1,12 @@
 {
   "globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
-  "ignores": ["docs/zh-CN/**", "docs/.i18n/**"],
+  "ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**"],
   "config": {
     "default": true,
 
     "MD013": false,
     "MD025": false,
-    "MD026": false,
     "MD029": false,
-    "MD030": false,
-    "MD031": false,
-    "MD032": false,
 
     "MD033": {
       "allowed_elements": [
@@ -48,9 +44,7 @@
       ],
     },
 
-    "MD034": false,
     "MD036": false,
-    "MD037": false,
     "MD040": false,
     "MD041": false,
     "MD046": false,

.oxlintrc.json

@@ -24,6 +24,7 @@
     "assets/",
     "dist/",
     "docs/_layouts/",
+    "extensions/",
     "node_modules/",
     "patches/",
     "pnpm-lock.yaml/",

CHANGELOG.md

@@ -2,29 +2,54 @@
 
 Docs: https://docs.openclaw.ai
 
-## 2026.2.4
+## 2026.2.6
+
+### Changes
+
+- Cron: default `wakeMode` is now `"now"` for new jobs (was `"next-heartbeat"`). (#10776) Thanks @tyler6204.
+- Cron: `cron run` defaults to force execution; use `--due` to restrict to due-only. (#10776) Thanks @tyler6204.
+- Models: support Anthropic Opus 4.6 and OpenAI Codex gpt-5.3-codex (forward-compat fallbacks). (#9853, #10720, #9995) Thanks @TinyTb, @calvin-hpnet, @tyler6204.
+- Providers: add xAI (Grok) support. (#9885) Thanks @grp06.
+- Providers: add Baidu Qianfan support. (#8868) Thanks @ide-rea.
+- Web UI: add token usage dashboard. (#10072) Thanks @Takhoffman.
+- Memory: native Voyage AI support. (#7078) Thanks @mcinteerj.
+- Sessions: cap sessions_history payloads to reduce context overflow. (#10000) Thanks @gut-puncture.
+- CLI: sort commands alphabetically in help output. (#8068) Thanks @deepsoumya617.
+- CI: optimize pipeline throughput (macOS consolidation, Windows perf, workflow concurrency). (#10784) Thanks @mcaxtr.
+- Agents: bump pi-mono to 0.52.7; add embedded forward-compat fallback for Opus 4.6 model ids.
+
+### Added
+
+- Cron: run history deep-links to session chat from the dashboard. (#10776) Thanks @tyler6204.
+- Cron: per-run session keys in run log entries and default labels for cron sessions. (#10776) Thanks @tyler6204.
+- Cron: legacy payload field compatibility (`deliver`, `channel`, `to`, `bestEffortDeliver`) in schema. (#10776) Thanks @tyler6204.
+
+### Fixes
+
+- 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.
+- 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.
+- Update: harden Control UI asset handling in update flow. (#10146) Thanks @gumadeiras.
+- Security: add skill/plugin code safety scanner; redact credentials from config.get gateway responses. (#9806, #9858) Thanks @abdelsfane.
+- Exec approvals: coerce bare string allowlist entries to objects. (#9903) Thanks @mcaxtr.
+- Slack: add mention stripPatterns for /new and /reset. (#9971) Thanks @ironbyte-rgb.
+- Chrome extension: fix bundled path resolution. (#8914) Thanks @kelvinCB.
+- Compaction/errors: allow multiple compaction retries on context overflow; show clear billing errors. (#8928, #8391) Thanks @Glucksberg.
+
+## 2026.2.3
 
 ### Changes
 
-- Agents: bump pi-mono packages to 0.52.5. (#9949) Thanks @gumadeiras.
-- Models: default Anthropic model to `anthropic/claude-opus-4-6`. (#9853) Thanks @TinyTb.
-- Models/Onboarding: refresh provider defaults, update OpenAI/OpenAI Codex wizard defaults, and harden model allowlist initialization for first-time configs with matching docs/tests. (#9911) Thanks @gumadeiras.
-- Telegram: auto-inject forum topic `threadId` in message tool and subagent announce so media, buttons, and subagent results land in the correct topic instead of General. (#7235) Thanks @Lukavyi.
-- Security: add skill/plugin code safety scanner that detects dangerous patterns (command injection, eval, data exfiltration, obfuscated code, crypto mining, env harvesting) in installed extensions. Integrated into `openclaw security audit --deep` and plugin install flow; scan failures surface as warnings. (#9806) Thanks @abdelsfane.
-- CLI: sort `openclaw --help` commands (and options) alphabetically. (#8068) Thanks @deepsoumya617.
 - Telegram: remove last `@ts-nocheck` from `bot-handlers.ts`, use Grammy types directly, deduplicate `StickerMetadata`. Zero `@ts-nocheck` remaining in `src/telegram/`. (#9206)
 - Telegram: remove `@ts-nocheck` from `bot-message.ts`, type deps via `Omit<BuildTelegramMessageContextParams>`, widen `allMedia` to `TelegramMediaRef[]`. (#9180)
 - Telegram: remove `@ts-nocheck` from `bot.ts`, fix duplicate `bot.catch` error handler (Grammy overrides), remove dead reaction `message_thread_id` routing, harden sticker cache guard. (#9077)
-- Telegram: allow per-group and per-topic `groupPolicy` overrides under `channels.telegram.groups`. (#9775) Thanks @nicolasstanley.
-- Feishu: expand channel handling (posts with images, doc links, routing, reactions/typing, replies, native commands). (#8975) Thanks @jiulingyun.
 - Onboarding: add Cloudflare AI Gateway provider setup and docs. (#7914) Thanks @roerohan.
 - Onboarding: add Moonshot (.cn) auth choice and keep the China base URL when preserving defaults. (#7180) Thanks @waynelwz.
-- Onboarding: add xAI (Grok) auth choice and provider defaults. (#9885) Thanks @grp06.
 - Docs: clarify tmux send-keys for TUI by splitting text and Enter. (#7737) Thanks @Wangnov.
-- Web UI: add Token Usage dashboard with session analytics. (#8462) Thanks @mcinteerj.
 - Docs: mirror the landing page revamp for zh-CN (features, quickstart, docs directory, network model, credits). (#8994) Thanks @joshp123.
-- Docs: strengthen secure DM mode guidance for multi-user inboxes with an explicit warning and example. (#9377) Thanks @Shrinija17.
-- Docs: document `activeHours` heartbeat field with timezone resolution chain and example. (#9366) Thanks @unisone.
 - Messages: add per-channel and per-account responsePrefix overrides across channels. (#9001) Thanks @mudrii.
 - Cron: add announce delivery mode for isolated jobs (CLI + Control UI) and delivery mode config.
 - Cron: default isolated jobs to announce delivery; accept ISO 8601 `schedule.at` in tool inputs.
@@ -35,33 +60,15 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
-- Control UI: add hardened fallback for asset resolution in global npm installs. (#4855) Thanks @anapivirtua.
-- Update: remove dead restore control-ui step that failed on gitignored dist/ output.
-- Update: avoid wiping prebuilt Control UI assets during dev auto-builds (`tsdown --no-clean`), run update doctor via `openclaw.mjs`, and auto-restore missing UI assets after doctor. (#10146) Thanks @gumadeiras.
-- Models: add forward-compat fallback for `openai-codex/gpt-5.3-codex` when model registry hasn't discovered it yet. (#9989) Thanks @w1kke.
-- Auto-reply/Docs: normalize `extra-high` (and spaced variants) to `xhigh` for Codex thinking levels, and align Codex 5.3 FAQ examples. (#9976) Thanks @slonce70.
-- Compaction: remove orphaned `tool_result` messages during history pruning to prevent session corruption from aborted tool calls. (#9868, fixes #9769, #9724, #9672)
-- Telegram: pass `parentPeer` for forum topic binding inheritance so group-level bindings apply to all topics within the group. (#9789, fixes #9545, #9351)
-- CLI: pass `--disable-warning=ExperimentalWarning` as a Node CLI option when respawning (avoid disallowed `NODE_OPTIONS` usage; fixes npm pack). (#9691) Thanks @18-RAJAT.
-- CLI: resolve bundled Chrome extension assets by walking up to the nearest assets directory; add resolver and clipboard tests. (#8914) Thanks @kelvinCB.
-- Tests: stabilize Windows ACL coverage with deterministic os.userInfo mocking. (#9335) Thanks @M00N7682.
-- Exec approvals: coerce bare string allowlist entries to objects to prevent allowlist corruption. (#9903, fixes #9790) Thanks @mcaxtr.
 - Heartbeat: allow explicit accountId routing for multi-account channels. (#8702) Thanks @lsh411.
 - TUI/Gateway: handle non-streaming finals, refresh history for non-local chat runs, and avoid event gap warnings for targeted tool streams. (#8432) Thanks @gumadeiras.
-- Security: stop exposing Gateway auth tokens via URL query parameters in Control UI entrypoints, and reject hook tokens in query parameters. (#9436) Thanks @coygeek.
 - Shell completion: auto-detect and migrate slow dynamic patterns to cached files for faster terminal startup; add completion health checks to doctor/update/onboard.
 - Telegram: honor session model overrides in inline model selection. (#8193) Thanks @gildo.
 - Web UI: fix agent model selection saves for default/non-default agents and wrap long workspace paths. Thanks @Takhoffman.
 - Web UI: resolve header logo path when `gateway.controlUi.basePath` is set. (#7178) Thanks @Yeom-JinHo.
 - Web UI: apply button styling to the new-messages indicator.
 - Onboarding: infer auth choice from non-interactive API key flags. (#8484) Thanks @f-trycua.
-- Usage: include estimated cost when breakdown is missing and keep `usage.cost` days support. (#8462) Thanks @mcinteerj.
 - Security: keep untrusted channel metadata out of system prompts (Slack/Discord). Thanks @KonstantinMirin.
-- Security: redact channel credentials (tokens, passwords, API keys, secrets) from gateway config APIs and preserve secrets during Control UI round-trips. (#9858) Thanks @abdelsfane.
-- Discord: treat allowlisted senders as owner for system-prompt identity hints while keeping channel topics untrusted.
-- Slack: strip `<@...>` mention tokens before command matching so `/new` and `/reset` work when prefixed with a mention. (#9971) Thanks @ironbyte-rgb.
-- Agents: cap `sessions_history` tool output and strip oversized fields to prevent context overflow. (#10000) Thanks @gut-puncture.
-- Security: normalize code safety finding paths in `openclaw security audit --deep` output for cross-platform consistency. (#10000) Thanks @gut-puncture.
 - Security: enforce sandboxed media paths for message tool attachments. (#9182) Thanks @victormier.
 - Security: require explicit credentials for gateway URL overrides to prevent credential leakage. (#8113) Thanks @victormier.
 - Security: gate `whatsapp_login` tool to owner senders and default-deny non-owner contexts. (#8768) Thanks @victormier.
@@ -69,13 +76,9 @@ Docs: https://docs.openclaw.ai
 - Voice call: add regression coverage for anonymous inbound caller IDs with allowlist policy. (#8104) Thanks @victormier.
 - Cron: accept epoch timestamps and 0ms durations in CLI `--at` parsing.
 - Cron: reload store data when the store file is recreated or mtime changes.
-- Cron: prevent `recomputeNextRuns` from skipping due jobs when timer fires late by reordering `onTimer` flow. (#9823, fixes #9788) Thanks @pycckuu.
 - Cron: deliver announce runs directly, honor delivery mode, and respect wakeMode for summaries. (#8540) Thanks @tyler6204.
-- Cron: correct announce delivery inference for thread session keys and null delivery inputs. (#9733) Thanks @tyler6204.
 - Telegram: include forward_from_chat metadata in forwarded messages and harden cron delivery target checks. (#8392) Thanks @Glucksberg.
-- Telegram: preserve DM topic threadId in deliveryContext. (#9039) Thanks @lailoo.
 - macOS: fix cron payload summary rendering and ISO 8601 formatter concurrency safety.
-- Security: require gateway auth for Canvas host and A2UI assets. (#9518) Thanks @coygeek.
 
 ## 2026.2.2-3
 

CLAUDE.md

@@ -1 +1 @@
-AGENTS.md
+AGENTS.md

CONTRIBUTING.md

@@ -25,6 +25,9 @@ Welcome to the lobster tank! 🦞
 - **Gustavo Madeira Santana** - Multi-agents, CLI, web UI
   - GitHub: [@gumadeiras](https://github.com/gumadeiras) · X: [@gumadeiras](https://x.com/gumadeiras)
 
+- **Maximilian Nussbaumer** - DevOps, CI/CD
+  - GitHub: [@quotentiroler](https://github.com/quotentiroler)
+
 ## How to Contribute
 
 1. **Bugs & small fixes** → Open a PR!
@@ -76,3 +79,44 @@ We are currently prioritizing:
 - **Performance**: Optimizing token usage and compaction logic.
 
 Check the [GitHub Issues](https://github.com/openclaw/openclaw/issues) for "good first issue" labels!
+
+## Core vs ClawHub
+
+Not everything belongs in the main repo. Here's how to decide:
+
+| Belongs in **Core**                            | Belongs on **[ClawHub](https://clawhub.ai)**         |
+| ---------------------------------------------- | ---------------------------------------------------- |
+| Channel integrations (Telegram, Discord, etc.) | Domain-specific skills (QR codes, image tools, etc.) |
+| CLI commands and infrastructure                | Custom workflows and automations                     |
+| Provider integrations (LLM backends)           | Niche or experimental utilities                      |
+| Security, routing, and core plumbing           | Third-party service integrations                     |
+
+**Rule of thumb:** if it adds new dependencies or is useful to some users but not most, it belongs on ClawHub. When in doubt, ask in Discord or open a Discussion before writing code.
+
+Skills submitted as PRs to this repo will be redirected to ClawHub. If the core maintainers later decide certain functionality should be first-party, it will be integrated into core.
+
+## Branch Strategy
+
+We use staged branch promotion to keep `main` stable:
+
+```
+dev/* / feature/* / fix/*  →  develop  →  alpha  →  beta  →  main
+```
+
+### For External Contributors
+
+1. Fork the repo
+2. Create your branch (`dev/my-feature`, `fix/some-bug`, etc.)
+3. Open a PR targeting `develop` (not `main`)
+4. CI runs lightweight checks only — no heavy platform tests on your PR
+5. Once merged to `develop`, your changes promote through alpha → beta → main automatically
+
+**Do not target `main`** — PRs to `main` will be redirected to `develop`.
+
+### For Maintainers
+
+- **Regular changes**: merge to `develop`, let the pipeline promote
+- **Hotfixes**: use `hotfix/*` branches for emergency fixes that bypass staging directly to `main`
+- **Docs-only changes**: skip the test pipeline automatically (paths-ignore)
+
+See [Pipeline docs](https://docs.openclaw.ai/reference/pipeline) for full details.

Dockerfile

@@ -44,5 +44,5 @@ USER node
 #
 # For container platforms requiring external health checks:
 #   1. Set OPENCLAW_GATEWAY_TOKEN or OPENCLAW_GATEWAY_PASSWORD env var
-#   2. Override CMD: ["node","dist/index.js","gateway","--allow-unconfigured","--bind","lan"]
-CMD ["node", "dist/index.js", "gateway", "--allow-unconfigured"]
+#   2. Override CMD: ["node","openclaw.mjs","gateway","--allow-unconfigured","--bind","lan"]
+CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]

apps/android/app/build.gradle.kts

@@ -22,7 +22,7 @@ android {
     minSdk = 31
     targetSdk = 36
     versionCode = 202602030
-    versionName = "2026.2.4"
+    versionName = "2026.2.6"
   }
 
   buildTypes {

apps/ios/Sources/Info.plist

@@ -19,7 +19,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.2.4</string>
+	<string>2026.2.6</string>
 	<key>CFBundleVersion</key>
 	<string>20260202</string>
 	<key>NSAppTransportSecurity</key>

apps/ios/Tests/Info.plist

@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.2.4</string>
+	<string>2026.2.6</string>
 	<key>CFBundleVersion</key>
 	<string>20260202</string>
 </dict>

apps/ios/project.yml

@@ -81,7 +81,7 @@ targets:
       properties:
         CFBundleDisplayName: OpenClaw
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.2.4"
+        CFBundleShortVersionString: "2026.2.6"
         CFBundleVersion: "20260202"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.2.4"
+        CFBundleShortVersionString: "2026.2.6"
         CFBundleVersion: "20260202"

apps/macos/Sources/OpenClaw/CronJobEditor.swift

@@ -29,7 +29,7 @@ struct CronJobEditor: View {
     @State var agentId: String = ""
     @State var enabled: Bool = true
     @State var sessionTarget: CronSessionTarget = .main
-    @State var wakeMode: CronWakeMode = .nextHeartbeat
+    @State var wakeMode: CronWakeMode = .now
     @State var deleteAfterRun: Bool = false
 
     enum ScheduleKind: String, CaseIterable, Identifiable { case at, every, cron; var id: String { rawValue } }
@@ -119,8 +119,8 @@ struct CronJobEditor: View {
                             GridRow {
                                 self.gridLabel("Wake mode")
                                 Picker("", selection: self.$wakeMode) {
-                                    Text("next-heartbeat").tag(CronWakeMode.nextHeartbeat)
                                     Text("now").tag(CronWakeMode.now)
+                                    Text("next-heartbeat").tag(CronWakeMode.nextHeartbeat)
                                 }
                                 .labelsHidden()
                                 .pickerStyle(.segmented)

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

@@ -15,7 +15,7 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.2.4</string>
+    <string>2026.2.6</string>
     <key>CFBundleVersion</key>
     <string>202602020</string>
     <key>CFBundleIconFile</key>

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2025,6 +2025,8 @@ public struct CronRunLogEntry: Codable, Sendable {
     public let status: AnyCodable?
     public let error: String?
     public let summary: String?
+    public let sessionid: String?
+    public let sessionkey: String?
     public let runatms: Int?
     public let durationms: Int?
     public let nextrunatms: Int?
@@ -2036,6 +2038,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         status: AnyCodable?,
         error: String?,
         summary: String?,
+        sessionid: String?,
+        sessionkey: String?,
         runatms: Int?,
         durationms: Int?,
         nextrunatms: Int?
@@ -2046,6 +2050,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         self.status = status
         self.error = error
         self.summary = summary
+        self.sessionid = sessionid
+        self.sessionkey = sessionkey
         self.runatms = runatms
         self.durationms = durationms
         self.nextrunatms = nextrunatms
@@ -2057,6 +2063,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         case status
         case error
         case summary
+        case sessionid = "sessionId"
+        case sessionkey = "sessionKey"
         case runatms = "runAtMs"
         case durationms = "durationMs"
         case nextrunatms = "nextRunAtMs"

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

@@ -2025,6 +2025,8 @@ public struct CronRunLogEntry: Codable, Sendable {
     public let status: AnyCodable?
     public let error: String?
     public let summary: String?
+    public let sessionid: String?
+    public let sessionkey: String?
     public let runatms: Int?
     public let durationms: Int?
     public let nextrunatms: Int?
@@ -2036,6 +2038,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         status: AnyCodable?,
         error: String?,
         summary: String?,
+        sessionid: String?,
+        sessionkey: String?,
         runatms: Int?,
         durationms: Int?,
         nextrunatms: Int?
@@ -2046,6 +2050,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         self.status = status
         self.error = error
         self.summary = summary
+        self.sessionid = sessionid
+        self.sessionkey = sessionkey
         self.runatms = runatms
         self.durationms = durationms
         self.nextrunatms = nextrunatms
@@ -2057,6 +2063,8 @@ public struct CronRunLogEntry: Codable, Sendable {
         case status
         case error
         case summary
+        case sessionid = "sessionId"
+        case sessionkey = "sessionKey"
         case runatms = "runAtMs"
         case durationms = "durationMs"
         case nextrunatms = "nextRunAtMs"

docs/automation/cron-jobs.md

@@ -17,6 +17,8 @@ the right time, and can optionally deliver output back to a chat.
 If you want _“run this every morning”_ or _“poke the agent in 20 minutes”_,
 cron is the mechanism.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## TL;DR
 
 - Cron runs **inside the Gateway** (not inside the model).
@@ -40,7 +42,7 @@ openclaw cron add \
   --delete-after-run
 
 openclaw cron list
-openclaw cron run <job-id> --force
+openclaw cron run <job-id>
 openclaw cron runs --id <job-id>
 ```
 
@@ -123,8 +125,8 @@ local timezone is used.
 Main jobs enqueue a system event and optionally wake the heartbeat runner.
 They must use `payload.kind = "systemEvent"`.
 
-- `wakeMode: "next-heartbeat"` (default): event waits for the next scheduled heartbeat.
-- `wakeMode: "now"`: event triggers an immediate heartbeat run.
+- `wakeMode: "now"` (default): event triggers an immediate heartbeat run.
+- `wakeMode: "next-heartbeat"`: event waits for the next scheduled heartbeat.
 
 This is the best fit when you want the normal heartbeat prompt + main-session context.
 See [Heartbeat](/gateway/heartbeat).
@@ -288,7 +290,7 @@ Notes:
 - `sessionTarget` must be `"main"` or `"isolated"` and must match `payload.kind`.
 - Optional fields: `agentId`, `description`, `enabled`, `deleteAfterRun` (defaults to true for `at`),
   `delivery`.
-- `wakeMode` defaults to `"next-heartbeat"` when omitted.
+- `wakeMode` defaults to `"now"` when omitted.
 
 ### cron.update params
 
@@ -420,10 +422,11 @@ openclaw cron edit <jobId> --agent ops
 openclaw cron edit <jobId> --clear-agent
 ```
 
-Manual run (debug):
+Manual run (force is the default, use `--due` to only run when due):
 
 ```bash
-openclaw cron run <jobId> --force
+openclaw cron run <jobId>
+openclaw cron run <jobId> --due
 ```
 
 Edit an existing job (patch fields):

docs/automation/troubleshooting.md

@@ -0,0 +1,122 @@
+---
+summary: "Troubleshoot cron and heartbeat scheduling and delivery"
+read_when:
+  - Cron did not run
+  - Cron ran but no message was delivered
+  - Heartbeat seems silent or skipped
+title: "Automation Troubleshooting"
+---
+
+# Automation troubleshooting
+
+Use this page for scheduler and delivery issues (`cron` + `heartbeat`).
+
+## Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then run automation checks:
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw system heartbeat last
+```
+
+## Cron not firing
+
+```bash
+openclaw cron status
+openclaw cron list
+openclaw cron runs --id <jobId> --limit 20
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- `cron status` reports enabled and a future `nextWakeAtMs`.
+- Job is enabled and has a valid schedule/timezone.
+- `cron runs` shows `ok` or explicit skip reason.
+
+Common signatures:
+
+- `cron: scheduler disabled; jobs will not run automatically` → cron disabled in config/env.
+- `cron: timer tick failed` → scheduler tick crashed; inspect surrounding stack/log context.
+- `reason: not-due` in run output → manual run called without `--force` and job not due yet.
+
+## Cron fired but no delivery
+
+```bash
+openclaw cron runs --id <jobId> --limit 20
+openclaw cron list
+openclaw channels status --probe
+openclaw logs --follow
+```
+
+Good output looks like:
+
+- Run status is `ok`.
+- Delivery mode/target are set for isolated jobs.
+- Channel probe reports target channel connected.
+
+Common signatures:
+
+- Run succeeded but delivery mode is `none` → no external message is expected.
+- Delivery target missing/invalid (`channel`/`to`) → run may succeed internally but skip outbound.
+- Channel auth errors (`unauthorized`, `missing_scope`, `Forbidden`) → delivery blocked by channel credentials/permissions.
+
+## Heartbeat suppressed or skipped
+
+```bash
+openclaw system heartbeat last
+openclaw logs --follow
+openclaw config get agents.defaults.heartbeat
+openclaw channels status --probe
+```
+
+Good output looks like:
+
+- Heartbeat enabled with non-zero interval.
+- Last heartbeat result is `ran` (or skip reason is understood).
+
+Common signatures:
+
+- `heartbeat skipped` with `reason=quiet-hours` → outside `activeHours`.
+- `requests-in-flight` → main lane busy; heartbeat deferred.
+- `empty-heartbeat-file` → `HEARTBEAT.md` exists but has no actionable content.
+- `alerts-disabled` → visibility settings suppress outbound heartbeat messages.
+
+## Timezone and activeHours gotchas
+
+```bash
+openclaw config get agents.defaults.heartbeat.activeHours
+openclaw config get agents.defaults.heartbeat.activeHours.timezone
+openclaw config get agents.defaults.userTimezone || echo "agents.defaults.userTimezone not set"
+openclaw cron list
+openclaw logs --follow
+```
+
+Quick rules:
+
+- `Config path not found: agents.defaults.userTimezone` means the key is unset; heartbeat falls back to host timezone (or `activeHours.timezone` if set).
+- Cron without `--tz` uses gateway host timezone.
+- Heartbeat `activeHours` uses configured timezone resolution (`user`, `local`, or explicit IANA tz).
+- ISO timestamps without timezone are treated as UTC for cron `at` schedules.
+
+Common signatures:
+
+- Jobs run at the wrong wall-clock time after host timezone changes.
+- Heartbeat always skipped during your daytime because `activeHours.timezone` is wrong.
+
+Related:
+
+- [/automation/cron-jobs](/automation/cron-jobs)
+- [/gateway/heartbeat](/gateway/heartbeat)
+- [/automation/cron-vs-heartbeat](/automation/cron-vs-heartbeat)
+- [/concepts/timezone](/concepts/timezone)

docs/brave-search.md

@@ -12,7 +12,7 @@ OpenClaw uses Brave Search as the default provider for `web_search`.
 
 ## Get an API key
 
-1. Create a Brave Search API account at https://brave.com/search/api/
+1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/)
 2. In the dashboard, choose the **Data for Search** plan and generate an API key.
 3. Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment.
 

docs/channels/bluebubbles.md

@@ -27,6 +27,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
 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: {
@@ -39,6 +40,7 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
      },
    }
    ```
+
 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.
 
@@ -335,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](/plugins) guide.
+For general channel workflow reference, see [Channels](/channels) and the [Plugins](/plugin) guide.

docs/channels/feishu.md

@@ -75,7 +75,7 @@ Choose **Feishu**, then enter the App ID and App Secret.
 
 Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.
 
-Lark (global) tenants should use https://open.larksuite.com/app and set `domain: "lark"` in the Feishu config.
+Lark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in the Feishu config.
 
 ### 2. Create an app
 
@@ -261,10 +261,12 @@ After approval, you can chat normally.
 
 - **Default**: `dmPolicy: "pairing"` (unknown users get a pairing code)
 - **Approve pairing**:
+
   ```bash
   openclaw pairing list feishu
   openclaw pairing approve feishu <CODE>
   ```
+
 - **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs
 
 ### Group chats

docs/channels/googlechat.md

@@ -101,6 +101,7 @@ Use Tailscale Serve for the private dashboard and Funnel for the public webhook
    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
@@ -225,6 +226,7 @@ This means the webhook handler isn't registered. Common causes:
    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
    ```

docs/channels/imessage.md

@@ -62,6 +62,28 @@ Disable with:
 - Automation permission when sending.
 - `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
 
+## Troubleshooting macOS Privacy and Security TCC
+
+If sending/receiving fails (for example, `imsg rpc` exits non-zero, times out, or the gateway appears to hang), a common cause is a macOS permission prompt that was never approved.
+
+macOS grants TCC permissions per app/process context. Approve prompts in the same context that runs `imsg` (for example, Terminal/iTerm, a LaunchAgent session, or an SSH-launched process).
+
+Checklist:
+
+- **Full Disk Access**: allow access for the process running OpenClaw (and any shell/SSH wrapper that executes `imsg`). This is required to read the Messages database (`chat.db`).
+- **Automation → Messages**: allow the process running OpenClaw (and/or your terminal) to control **Messages.app** for outbound sends.
+- **`imsg` CLI health**: verify `imsg` is installed and supports RPC (`imsg rpc --help`).
+
+Tip: If OpenClaw is running headless (LaunchAgent/systemd/SSH) the macOS prompt can be easy to miss. Run a one-time interactive command in a GUI terminal to force the prompt, then retry:
+
+```bash
+imsg chats --limit 1
+# or
+imsg send <handle> "test"
+```
+
+Related macOS folder permissions (Desktop/Documents/Downloads): [/platforms/mac/permissions](/platforms/mac/permissions).
+
 ## Setup (fast path)
 
 1. Ensure Messages is signed in on this Mac.
@@ -81,7 +103,7 @@ If you want the bot to send from a **separate iMessage identity** (and keep your
 6. Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.
 7. Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.
 
-First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.
+First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the _bot macOS user_. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry. See [Troubleshooting macOS Privacy and Security TCC](#troubleshooting-macos-privacy-and-security-tcc).
 
 Example wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:
 

docs/channels/line.md

@@ -34,7 +34,7 @@ openclaw plugins install ./extensions/line
 ## Setup
 
 1. Create a LINE Developers account and open the Console:
-   https://developers.line.biz/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.

docs/channels/matrix.md

@@ -74,7 +74,7 @@ Details: [Plugins](/plugin)
    - When set, `channels.matrix.userId` should be the full Matrix ID (example: `@bot:example.org`).
 5. Restart the gateway (or finish onboarding).
 6. Start a DM with the bot or invite it to a room from any Matrix client
-   (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE,
+   (Element, Beeper, etc.; see [https://matrix.org/ecosystem/clients/](https://matrix.org/ecosystem/clients/)). Beeper requires E2EE,
    so set `channels.matrix.encryption: true` and verify the device.
 
 Minimal config (access token, user ID auto-fetched):
@@ -202,6 +202,32 @@ Once verified, the bot can decrypt messages in encrypted rooms.
 | Location        | ✅ Supported (geo URI; altitude ignored)                                              |
 | Native commands | ✅ Supported                                                                          |
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list matrix
+```
+
+Common failures:
+
+- Logged in but room messages ignored: room blocked by `groupPolicy` or room allowlist.
+- DMs ignored: sender pending approval when `channels.matrix.dm.policy="pairing"`.
+- Encrypted rooms fail: crypto support or encryption settings mismatch.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Matrix)
 
 Full configuration: [Configuration](/gateway/configuration)

docs/channels/msteams.md

@@ -558,6 +558,7 @@ Bots don't have a personal OneDrive drive (the `/me/drive` Graph API endpoint do
    ```
 
 4. **Configure OpenClaw:**
+
    ```json5
    {
      channels: {
@@ -747,7 +748,7 @@ Bots have limited support in private channels:
 
 - **"Icon file cannot be empty":** The manifest references icon files that are 0 bytes. Create valid PNG icons (32x32 for `outline.png`, 192x192 for `color.png`).
 - **"webApplicationInfo.Id already in use":** The app is still installed in another team/chat. Find and uninstall it first, or wait 5-10 minutes for propagation.
-- **"Something went wrong" on upload:** Upload via https://admin.teams.microsoft.com instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error.
+- **"Something went wrong" on upload:** Upload via [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) instead, open browser DevTools (F12) → Network tab, and check the response body for the actual error.
 - **Sideload failing:** Try "Upload an app to your org's app catalog" instead of "Upload a custom app" - this often bypasses sideload restrictions.
 
 ### RSC permissions not working

docs/channels/nextcloud-talk.md

@@ -34,9 +34,11 @@ Details: [Plugins](/plugin)
 
 1. Install the Nextcloud Talk plugin.
 2. On your Nextcloud server, create a bot:
+
    ```bash
    ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
    ```
+
 3. Enable the bot in the target room settings.
 4. Configure OpenClaw:
    - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`

docs/channels/signal.md

@@ -168,6 +168,32 @@ Config:
 - Groups: `signal:group:<groupId>`.
 - Usernames: `username:<name>` (if supported by your Signal account).
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list signal
+```
+
+Common failures:
+
+- Daemon reachable but no replies: verify account/daemon settings (`httpUrl`, `account`) and receive mode.
+- DMs ignored: sender is pending pairing approval.
+- Group messages ignored: group sender/mention gating blocks delivery.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Configuration reference (Signal)
 
 Full configuration: [Configuration](/gateway/configuration)

docs/channels/slack.md

@@ -30,7 +30,7 @@ Minimal config:
 
 ### Setup
 
-1. Create a Slack app (From scratch) in https://api.slack.com/apps.
+1. Create a Slack app (From scratch) in [https://api.slack.com/apps](https://api.slack.com/apps).
 2. **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
 3. **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
 4. Optional: **OAuth & Permissions** → add **User Token Scopes** (see the read-only list below). Reinstall the app and copy the **User OAuth Token** (`xoxp-...`).
@@ -260,30 +260,30 @@ If you enable native commands, add one `slash_commands` entry per command you wa
 
 Slack's Conversations API is type-scoped: you only need the scopes for the
 conversation types you actually touch (channels, groups, im, mpim). See
-https://docs.slack.dev/apis/web-api/using-the-conversations-api/ for the overview.
+[https://docs.slack.dev/apis/web-api/using-the-conversations-api/](https://docs.slack.dev/apis/web-api/using-the-conversations-api/) for the overview.
 
 ### Bot token scopes (required)
 
 - `chat:write` (send/update/delete messages via `chat.postMessage`)
-  https://docs.slack.dev/reference/methods/chat.postMessage
+  [https://docs.slack.dev/reference/methods/chat.postMessage](https://docs.slack.dev/reference/methods/chat.postMessage)
 - `im:write` (open DMs via `conversations.open` for user DMs)
-  https://docs.slack.dev/reference/methods/conversations.open
+  [https://docs.slack.dev/reference/methods/conversations.open](https://docs.slack.dev/reference/methods/conversations.open)
 - `channels:history`, `groups:history`, `im:history`, `mpim:history`
-  https://docs.slack.dev/reference/methods/conversations.history
+  [https://docs.slack.dev/reference/methods/conversations.history](https://docs.slack.dev/reference/methods/conversations.history)
 - `channels:read`, `groups:read`, `im:read`, `mpim:read`
-  https://docs.slack.dev/reference/methods/conversations.info
+  [https://docs.slack.dev/reference/methods/conversations.info](https://docs.slack.dev/reference/methods/conversations.info)
 - `users:read` (user lookup)
-  https://docs.slack.dev/reference/methods/users.info
+  [https://docs.slack.dev/reference/methods/users.info](https://docs.slack.dev/reference/methods/users.info)
 - `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
-  https://docs.slack.dev/reference/methods/reactions.get
-  https://docs.slack.dev/reference/methods/reactions.add
+  [https://docs.slack.dev/reference/methods/reactions.get](https://docs.slack.dev/reference/methods/reactions.get)
+  [https://docs.slack.dev/reference/methods/reactions.add](https://docs.slack.dev/reference/methods/reactions.add)
 - `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
-  https://docs.slack.dev/reference/scopes/pins.read
-  https://docs.slack.dev/reference/scopes/pins.write
+  [https://docs.slack.dev/reference/scopes/pins.read](https://docs.slack.dev/reference/scopes/pins.read)
+  [https://docs.slack.dev/reference/scopes/pins.write](https://docs.slack.dev/reference/scopes/pins.write)
 - `emoji:read` (`emoji.list`)
-  https://docs.slack.dev/reference/scopes/emoji.read
+  [https://docs.slack.dev/reference/scopes/emoji.read](https://docs.slack.dev/reference/scopes/emoji.read)
 - `files:write` (uploads via `files.uploadV2`)
-  https://docs.slack.dev/messaging/working-with-files/#upload
+  [https://docs.slack.dev/messaging/working-with-files/#upload](https://docs.slack.dev/messaging/working-with-files/#upload)
 
 ### User token scopes (optional, read-only by default)
 
@@ -302,9 +302,9 @@ Add these under **User Token Scopes** if you configure `channels.slack.userToken
 - `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
 - `groups:write` (only if we add private-channel management: create/rename/invite/archive)
 - `chat:write.public` (only if we want to post to channels the bot isn't in)
-  https://docs.slack.dev/reference/scopes/chat.write.public
+  [https://docs.slack.dev/reference/scopes/chat.write.public](https://docs.slack.dev/reference/scopes/chat.write.public)
 - `users:read.email` (only if we need email fields from `users.info`)
-  https://docs.slack.dev/changelog/2017-04-narrowing-email-access
+  [https://docs.slack.dev/changelog/2017-04-narrowing-email-access](https://docs.slack.dev/changelog/2017-04-narrowing-email-access)
 - `files:read` (only if we start listing/reading file metadata)
 
 ## Config
@@ -537,6 +537,32 @@ Slack tool actions can be gated with `channels.slack.actions.*`:
   scopes you expect (`chat:write`, `reactions:write`, `pins:write`,
   `files:write`) or those operations will fail.
 
+## Troubleshooting
+
+Run this ladder first:
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then confirm DM pairing state if needed:
+
+```bash
+openclaw pairing list slack
+```
+
+Common failures:
+
+- Connected but no channel replies: channel blocked by `groupPolicy` or not in `channels.slack.channels` allowlist.
+- DMs ignored: sender not approved when `channels.slack.dm.policy="pairing"`.
+- API errors (`missing_scope`, `not_in_channel`, auth failures): bot/app tokens or Slack scopes are incomplete.
+
+For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+
 ## Notes
 
 - Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.

docs/channels/telegram.md

@@ -365,6 +365,7 @@ Alternate (official Bot API):
 
 1. DM your bot.
 2. Fetch updates with your bot token and read `message.from.id`:
+
    ```bash
    curl "https://api.telegram.org/bot<bot_token>/getUpdates"
    ```

docs/channels/troubleshooting.md

@@ -1,29 +1,116 @@
 ---
-summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp)"
+summary: "Fast channel level troubleshooting with per channel failure signatures and fixes"
 read_when:
-  - A channel connects but messages don’t flow
-  - Investigating channel misconfiguration (intents, permissions, privacy mode)
+  - Channel transport says connected but replies fail
+  - You need channel specific checks before deep provider docs
 title: "Channel Troubleshooting"
 ---
 
 # Channel troubleshooting
 
-Start with:
+Use this page when a channel connects but behavior is wrong.
+
+## Command ladder
+
+Run these in order first:
 
 ```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
 openclaw doctor
 openclaw channels status --probe
 ```
 
-`channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership).
+Healthy baseline:
 
-## Channels
+- `Runtime: running`
+- `RPC probe: ok`
+- Channel probe shows connected/ready
 
-- Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
-- Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
-- WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+## WhatsApp
 
-## Telegram quick fixes
+### WhatsApp failure signatures
 
-- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting).
-- Logs show `setMyCommands failed` → check outbound HTTPS and DNS reachability to `api.telegram.org` (common on locked-down VPS or proxies).
+| Symptom                         | Fastest check                                       | Fix                                                     |
+| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
+| Connected but no DM replies     | `openclaw pairing list whatsapp`                    | Approve sender or switch DM policy/allowlist.           |
+| Group messages ignored          | Check `requireMention` + mention patterns in config | Mention the bot or relax mention policy for that group. |
+| Random disconnect/relogin loops | `openclaw channels status --probe` + logs           | Re-login and verify credentials directory is healthy.   |
+
+Full troubleshooting: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)
+
+## Telegram
+
+### Telegram failure signatures
+
+| Symptom                           | Fastest check                                   | Fix                                                       |
+| --------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
+| `/start` but no usable reply flow | `openclaw pairing list telegram`                | Approve pairing or change DM policy.                      |
+| Bot online but group stays silent | Verify mention requirement and bot privacy mode | Disable privacy mode for group visibility or mention bot. |
+| Send failures with network errors | Inspect logs for Telegram API call failures     | Fix DNS/IPv6/proxy routing to `api.telegram.org`.         |
+
+Full troubleshooting: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+
+## Discord
+
+### Discord failure signatures
+
+| Symptom                         | Fastest check                       | Fix                                                       |
+| ------------------------------- | ----------------------------------- | --------------------------------------------------------- |
+| Bot online but no guild replies | `openclaw channels status --probe`  | Allow guild/channel and verify message content intent.    |
+| Group messages ignored          | Check logs for mention gating drops | Mention bot or set guild/channel `requireMention: false`. |
+| DM replies missing              | `openclaw pairing list discord`     | Approve DM pairing or adjust DM policy.                   |
+
+Full troubleshooting: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+
+## Slack
+
+### Slack failure signatures
+
+| Symptom                                | Fastest check                             | Fix                                               |
+| -------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| Socket mode connected but no responses | `openclaw channels status --probe`        | Verify app token + bot token and required scopes. |
+| DMs blocked                            | `openclaw pairing list slack`             | Approve pairing or relax DM policy.               |
+| Channel message ignored                | Check `groupPolicy` and channel allowlist | Allow the channel or switch policy to `open`.     |
+
+Full troubleshooting: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
+
+## iMessage and BlueBubbles
+
+### iMessage and BlueBubbles failure signatures
+
+| Symptom                          | Fastest check                                                           | Fix                                                   |
+| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
+| No inbound events                | Verify webhook/server reachability and app permissions                  | Fix webhook URL or BlueBubbles server state.          |
+| Can send but no receive on macOS | Check macOS privacy permissions for Messages automation                 | Re-grant TCC permissions and restart channel process. |
+| DM sender blocked                | `openclaw pairing list imessage` or `openclaw pairing list bluebubbles` | Approve pairing or update allowlist.                  |
+
+Full troubleshooting:
+
+- [/channels/imessage#troubleshooting-macos-privacy-and-security-tcc](/channels/imessage#troubleshooting-macos-privacy-and-security-tcc)
+- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
+
+## Signal
+
+### Signal failure signatures
+
+| Symptom                         | Fastest check                              | Fix                                                      |
+| ------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
+| Daemon reachable but bot silent | `openclaw channels status --probe`         | Verify `signal-cli` daemon URL/account and receive mode. |
+| DM blocked                      | `openclaw pairing list signal`             | Approve sender or adjust DM policy.                      |
+| Group replies do not trigger    | Check group allowlist and mention patterns | Add sender/group or loosen gating.                       |
+
+Full troubleshooting: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
+
+## Matrix
+
+### Matrix failure signatures
+
+| Symptom                             | Fastest check                                | Fix                                             |
+| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- |
+| Logged in but ignores room messages | `openclaw channels status --probe`           | Check `groupPolicy` and room allowlist.         |
+| DMs do not process                  | `openclaw pairing list matrix`               | Approve sender or adjust DM policy.             |
+| Encrypted rooms fail                | Verify crypto module and encryption settings | Enable encryption support and rejoin/sync room. |
+
+Full troubleshooting: [/channels/matrix#troubleshooting](/channels/matrix#troubleshooting)

docs/channels/twitch.md

@@ -34,7 +34,7 @@ Details: [Plugins](/plugin)
    - Select **Bot Token**
    - Verify scopes `chat:read` and `chat:write` are selected
    - Copy the **Client ID** and **Access Token**
-3. Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
+3. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
 4. Configure the token:
    - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (default account only)
    - Or config: `channels.twitch.accessToken`
@@ -123,7 +123,7 @@ Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want
 
 **Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
 
-Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Convert your Twitch username to ID)
+Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/) (Convert your Twitch username to ID)
 
 ## Token refresh (optional)
 

docs/channels/whatsapp.md

@@ -205,11 +205,13 @@ The wizard uses it to set your **allowlist/owner** so your own DMs are permitted
 
 - `Body` is the current message body with envelope.
 - Quoted reply context is **always appended**:
+
   ```
   [Replying to +1555 id:ABC123]
   <quoted text or <media:...>>
   [/Replying]
   ```
+
 - Reply metadata also set:
   - `ReplyToId` = stanzaId
   - `ReplyToBody` = quoted body or media placeholder

docs/channels/zalo.md

@@ -57,7 +57,7 @@ It is a good fit for support or notifications where you want deterministic routi
 
 ### 1) Create a bot token (Zalo Bot Platform)
 
-1. Go to **https://bot.zaloplatforms.com** and sign in.
+1. Go to [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) and sign in.
 2. Create a new bot and configure its settings.
 3. Copy the bot token (format: `12345689:abc-xyz`).
 

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](/plugins)
+- Plugins: [Plugins](/plugin)
 
 ## Examples
 

docs/concepts/architecture.md

@@ -110,9 +110,11 @@ Details: [Gateway protocol](/gateway/protocol), [Pairing](/start/pairing),
 
 - Preferred: Tailscale or VPN.
 - Alternative: SSH tunnel
+
   ```bash
   ssh -N -L 18789:127.0.0.1:18789 user@host
   ```
+
 - The same handshake + auth token apply over the tunnel.
 - TLS + optional pinning can be enabled for WS in remote setups.
 

docs/concepts/memory.md

@@ -88,7 +88,8 @@ Defaults:
   1. `local` if a `memorySearch.local.modelPath` is configured and the file exists.
   2. `openai` if an OpenAI key can be resolved.
   3. `gemini` if a Gemini key can be resolved.
-  4. Otherwise memory search stays disabled until configured.
+  4. `voyage` if a Voyage key can be resolved.
+  5. Otherwise memory search stays disabled until configured.
 - Local mode uses node-llama-cpp and may require `pnpm approve-builds`.
 - Uses sqlite-vec (when available) to accelerate vector search inside SQLite.
 
@@ -96,7 +97,8 @@ Remote embeddings **require** an API key for the embedding provider. OpenClaw
 resolves keys from auth profiles, `models.providers.*.apiKey`, or environment
 variables. Codex OAuth only covers chat/completions and does **not** satisfy
 embeddings for memory search. For Gemini, use `GEMINI_API_KEY` or
-`models.providers.google.apiKey`. When using a custom OpenAI-compatible endpoint,
+`models.providers.google.apiKey`. For Voyage, use `VOYAGE_API_KEY` or
+`models.providers.voyage.apiKey`. When using a custom OpenAI-compatible endpoint,
 set `memorySearch.remote.apiKey` (and optional `memorySearch.remote.headers`).
 
 ### QMD backend (experimental)
@@ -109,7 +111,7 @@ out to QMD for retrieval. Key points:
 **Prereqs**
 
 - Disabled by default. Opt in per-config (`memory.backend = "qmd"`).
-- Install the QMD CLI separately (`bun install -g github.com/tobi/qmd` or grab
+- Install the QMD CLI separately (`bun install -g https://github.com/tobi/qmd` or grab
   a release) and make sure the `qmd` binary is on the gateway’s `PATH`.
 - QMD needs an SQLite build that allows extensions (`brew install sqlite` on
   macOS).
@@ -302,8 +304,8 @@ Why OpenAI batch is fast + cheap:
 - For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously.
 - OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously.
 - See the OpenAI Batch API docs and pricing for details:
-  - https://platform.openai.com/docs/api-reference/batch
-  - https://platform.openai.com/pricing
+  - [https://platform.openai.com/docs/api-reference/batch](https://platform.openai.com/docs/api-reference/batch)
+  - [https://platform.openai.com/pricing](https://platform.openai.com/pricing)
 
 Config example:
 

docs/concepts/model-providers.md

@@ -136,14 +136,14 @@ Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:
 
 Kimi K2 model IDs:
 
-{/_ moonshot-kimi-k2-model-refs:start _/ && null}
+{/_moonshot-kimi-k2-model-refs:start_/ && null}
 
 - `moonshot/kimi-k2.5`
 - `moonshot/kimi-k2-0905-preview`
 - `moonshot/kimi-k2-turbo-preview`
 - `moonshot/kimi-k2-thinking`
 - `moonshot/kimi-k2-thinking-turbo`
-  {/_ moonshot-kimi-k2-model-refs:end _/ && null}
+  {/_moonshot-kimi-k2-model-refs:end_/ && null}
 
 ```json5
 {
@@ -242,7 +242,7 @@ Ollama is a local LLM runtime that provides an OpenAI-compatible API:
 - Provider: `ollama`
 - Auth: None required (local server)
 - Example model: `ollama/llama3.3`
-- Installation: https://ollama.ai
+- Installation: [https://ollama.ai](https://ollama.ai)
 
 ```bash
 # Install Ollama, then pull a model:

docs/concepts/system-prompt.md

@@ -110,6 +110,6 @@ This keeps the base prompt small while still enabling targeted skill usage.
 When available, the system prompt includes a **Documentation** section that points to the
 local OpenClaw docs directory (either `docs/` in the repo workspace or the bundled npm
 package docs) and also notes the public mirror, source repo, community Discord, and
-ClawHub (https://clawhub.com) for skills discovery. The prompt instructs the model to consult local docs first
+ClawHub ([https://clawhub.com](https://clawhub.com)) for skills discovery. The prompt instructs the model to consult local docs first
 for OpenClaw behavior, commands, configuration, or architecture, and to run
 `openclaw status` itself when possible (asking the user only when it lacks access).

docs/concepts/typebox.md

@@ -280,7 +280,7 @@ Unknown frame types are preserved as raw payloads for forward compatibility.
 Generated JSON Schema is in the repo at `dist/protocol.schema.json`. The
 published raw file is typically available at:
 
-- https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json
+- [https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json](https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json)
 
 ## When you change schemas
 

docs/debug/node-issue.md

@@ -62,19 +62,21 @@ node --import tsx scripts/repro/tsx-name-repro.ts
 
 - Use Bun for dev scripts (current temporary revert).
 - Use Node + tsc watch, then run compiled output:
+
   ```bash
   pnpm exec tsc --watch --preserveWatchOutput
   node --watch openclaw.mjs status
   ```
+
 - Confirmed locally: `pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` works on Node 25.
 - Disable esbuild keepNames in the TS loader if possible (prevents `__name` helper insertion); tsx does not currently expose this.
 - Test Node LTS (22/24) with `tsx` to see if the issue is Node 25–specific.
 
 ## References
 
-- https://opennext.js.org/cloudflare/howtos/keep_names
-- https://esbuild.github.io/api/#keep-names
-- https://github.com/evanw/esbuild/issues/1031
+- [https://opennext.js.org/cloudflare/howtos/keep_names](https://opennext.js.org/cloudflare/howtos/keep_names)
+- [https://esbuild.github.io/api/#keep-names](https://esbuild.github.io/api/#keep-names)
+- [https://github.com/evanw/esbuild/issues/1031](https://github.com/evanw/esbuild/issues/1031)
 
 ## Next steps
 

docs/docs.json

@@ -98,6 +98,10 @@
       "source": "/opencode",
       "destination": "/providers/opencode"
     },
+    {
+      "source": "/qianfan",
+      "destination": "/providers/qianfan"
+    },
     {
       "source": "/mattermost",
       "destination": "/channels/mattermost"
@@ -660,7 +664,7 @@
     },
     {
       "source": "/troubleshooting",
-      "destination": "/gateway/troubleshooting"
+      "destination": "/help/troubleshooting"
     },
     {
       "source": "/web/tui",
@@ -962,6 +966,7 @@
                   "hooks/soul-evil",
                   "automation/cron-jobs",
                   "automation/cron-vs-heartbeat",
+                  "automation/troubleshooting",
                   "automation/webhook",
                   "automation/gmail-pubsub",
                   "automation/poll",
@@ -972,6 +977,7 @@
                 "group": "Media and devices",
                 "pages": [
                   "nodes/index",
+                  "nodes/troubleshooting",
                   "nodes/images",
                   "nodes/audio",
                   "nodes/camera",
@@ -1006,7 +1012,8 @@
                   "providers/opencode",
                   "providers/glm",
                   "providers/zai",
-                  "providers/synthetic"
+                  "providers/synthetic",
+                  "providers/qianfan"
                 ]
               }
             ]

docs/gateway/bonjour.md

@@ -105,10 +105,13 @@ The Gateway advertises small non‑secret hints to make UI flows convenient:
 Useful built‑in tools:
 
 - Browse instances:
+
   ```bash
   dns-sd -B _openclaw-gw._tcp local.
   ```
+
 - Resolve one instance (replace `<instance>`):
+
   ```bash
   dns-sd -L "<instance>" _openclaw-gw._tcp local.
   ```

docs/gateway/configuration.md

@@ -1453,7 +1453,7 @@ working directory). The path must exist to be used.
 
 ### `agents.defaults.skipBootstrap`
 
-Disables automatic creation of the workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, and `BOOTSTRAP.md`).
+Disables automatic creation of the workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, and `BOOTSTRAP.md`).
 
 Use this for pre-seeded deployments where your workspace files come from a repo.
 
@@ -1978,11 +1978,13 @@ Block streaming:
 - `agents.defaults.blockStreamingChunk`: soft chunking for streamed blocks. Defaults to
   800–1200 chars, prefers paragraph breaks (`\n\n`), then newlines, then sentences.
   Example:
+
   ```json5
   {
     agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
   }
   ```
+
 - `agents.defaults.blockStreamingCoalesce`: merge streamed blocks before sending.
   Defaults to `{ idleMs: 1000 }` and inherits `minChars` from `blockStreamingChunk`
   with `maxChars` capped to the channel text limit. Signal/Slack/Discord/Google Chat default
@@ -1996,11 +1998,13 @@ Block streaming:
   Modes: `off` (default), `natural` (800–2500ms), `custom` (use `minMs`/`maxMs`).
   Per-agent override: `agents.list[].humanDelay`.
   Example:
+
   ```json5
   {
     agents: { defaults: { humanDelay: { mode: "natural" } } },
   }
   ```
+
   See [/concepts/streaming](/concepts/streaming) for behavior + chunking details.
 
 Typing indicators:
@@ -2066,7 +2070,7 @@ of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.
 - `tools.web.fetch.readability` (default true; disable to use basic HTML cleanup only)
 - `tools.web.fetch.firecrawl.enabled` (default true when an API key is set)
 - `tools.web.fetch.firecrawl.apiKey` (optional; defaults to `FIRECRAWL_API_KEY`)
-- `tools.web.fetch.firecrawl.baseUrl` (default https://api.firecrawl.dev)
+- `tools.web.fetch.firecrawl.baseUrl` (default [https://api.firecrawl.dev](https://api.firecrawl.dev))
 - `tools.web.fetch.firecrawl.onlyMainContent` (default true)
 - `tools.web.fetch.firecrawl.maxAgeMs` (optional)
 - `tools.web.fetch.firecrawl.timeoutSeconds` (optional)
@@ -2482,7 +2486,7 @@ Select the model via `agents.defaults.model.primary` (provider/model).
 
 OpenCode Zen is a multi-model gateway with per-model endpoints. OpenClaw uses
 the built-in `opencode` provider from pi-ai; set `OPENCODE_API_KEY` (or
-`OPENCODE_ZEN_API_KEY`) from https://opencode.ai/auth.
+`OPENCODE_ZEN_API_KEY`) from [https://opencode.ai/auth](https://opencode.ai/auth).
 
 Notes:
 

docs/gateway/heartbeat.md

@@ -13,6 +13,8 @@ title: "Heartbeat"
 Heartbeat runs **periodic agent turns** in the main session so the model can
 surface anything that needs attention without spamming you.
 
+Troubleshooting: [/automation/troubleshooting](/automation/troubleshooting)
+
 ## Quick start (beginner)
 
 1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.

docs/gateway/index.md

@@ -49,9 +49,11 @@ pnpm gateway:watch
 ## Remote access
 
 - Tailscale/VPN preferred; otherwise SSH tunnel:
+
   ```bash
   ssh -N -L 18789:127.0.0.1:18789 user@host
   ```
+
 - Clients then connect to `ws://127.0.0.1:18789` through the tunnel.
 - If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel.
 

docs/gateway/local-models.md

@@ -52,7 +52,7 @@ Best current local stack. Load MiniMax M2.1 in LM Studio, enable the local serve
 
 **Setup checklist**
 
-- Install LM Studio: https://lmstudio.ai
+- Install LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
 - In LM Studio, download the **largest MiniMax M2.1 build available** (avoid “small”/heavily quantized variants), start the server, confirm `http://127.0.0.1:1234/v1/models` lists it.
 - Keep the model loaded; cold-load adds startup latency.
 - Adjust `contextWindow`/`maxTokens` if your LM Studio build differs.

docs/gateway/security/formal-verification.md

@@ -23,7 +23,7 @@ misconfiguration safety), under explicit assumptions.
 
 ## Where the models live
 
-Models are maintained in a separate repo: [vignesh07/openclaw-formal-models](https://github.com/vignesh07/openclaw-formal-models).
+Models are maintained in a separate repo: [vignesh07/clawdbot-formal-models](https://github.com/vignesh07/clawdbot-formal-models).
 
 ## Important caveats
 
@@ -41,8 +41,8 @@ Today, results are reproduced by cloning the models repo locally and running TLC
 Getting started:
 
 ```bash
-git clone https://github.com/vignesh07/openclaw-formal-models
-cd openclaw-formal-models
+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.

docs/gateway/security/index.md

@@ -773,18 +773,22 @@ If it fails, there are new candidates not yet in the baseline.
 ### If CI fails
 
 1. Reproduce locally:
+
    ```bash
    detect-secrets scan --baseline .secrets.baseline
    ```
+
 2. Understand the tools:
    - `detect-secrets scan` finds candidates and compares them to the baseline.
    - `detect-secrets audit` opens an interactive review to mark each baseline
      item as real or false positive.
 3. For real secrets: rotate/remove them, then re-run the scan to update the baseline.
 4. For false positives: run the interactive audit and mark them as false:
+
    ```bash
    detect-secrets audit .secrets.baseline
    ```
+
 5. If you need new excludes, add them to `.detect-secrets.cfg` and regenerate the
    baseline with matching `--exclude-files` / `--exclude-lines` flags (the config
    file is reference-only; detect-secrets doesn’t read it automatically).
@@ -814,7 +818,7 @@ Mario asking for find ~
 
 Found a vulnerability in OpenClaw? Please report responsibly:
 
-1. Email: security@openclaw.ai
+1. Email: [security@openclaw.ai](mailto:security@openclaw.ai)
 2. Don't post publicly until fixed
 3. We'll credit you (unless you prefer anonymity)
 

docs/gateway/tailscale.md

@@ -121,7 +121,7 @@ Avoid Funnel for browser control; treat node pairing like operator access.
 
 ## Learn more
 
-- Tailscale Serve overview: https://tailscale.com/kb/1312/serve
-- `tailscale serve` command: https://tailscale.com/kb/1242/tailscale-serve
-- Tailscale Funnel overview: https://tailscale.com/kb/1223/tailscale-funnel
-- `tailscale funnel` command: https://tailscale.com/kb/1311/tailscale-funnel
+- Tailscale Serve overview: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
+- `tailscale serve` command: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
+- Tailscale Funnel overview: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
+- `tailscale funnel` command: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)

docs/help/faq.md

@@ -252,10 +252,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
    Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor).
 
 7. **Gateway snapshot**
+
    ```bash
    openclaw health --json
    openclaw health --verbose   # shows the target URL + config path on errors
    ```
+
    Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).
 
 ## Quick start and first-run setup
@@ -266,8 +268,8 @@ Use a local AI agent that can **see your machine**. That is far more effective t
 in Discord, because most "I'm stuck" cases are **local config or environment issues** that
 remote helpers cannot inspect.
 
-- **Claude Code**: https://www.anthropic.com/claude-code/
-- **OpenAI Codex**: https://openai.com/codex/
+- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
+- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
 
 These tools can read the repo, run commands, inspect logs, and help fix your machine-level
 setup (PATH, services, permissions, auth files). Give them the **full source checkout** via
@@ -285,8 +287,8 @@ Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execut
 necessary commands. That keeps changes small and easier to audit.
 
 If you discover a real bug or fix, please file a GitHub issue or send a PR:
-https://github.com/openclaw/openclaw/issues
-https://github.com/openclaw/openclaw/pulls
+[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
+[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
 
 Start with these commands (share outputs when asking for help):
 
@@ -432,7 +434,7 @@ Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#
 ### Where do I see what is new in the latest version
 
 Check the GitHub changelog:
-https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
+[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
 
 Newest entries are at the top. If the top section is marked **Unreleased**, the next dated
 section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and
@@ -443,10 +445,10 @@ section is the latest shipped version. Entries are grouped by **Highlights**, **
 Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
 Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More
 detail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity).
-Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status.
+Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
 
 If you still can't reach the site, the docs are mirrored on GitHub:
-https://github.com/openclaw/openclaw/tree/main/docs
+[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
 
 ### What's the difference between stable and beta
 
@@ -460,7 +462,7 @@ that same version to `latest`**. That's why beta and stable can point at the
 **same version**.
 
 See what changed:
-https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
+[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
 
 ### How do I install the beta version and whats the difference between beta and dev
 
@@ -478,7 +480,7 @@ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -
 ```
 
 Windows installer (PowerShell):
-https://openclaw.ai/install.ps1
+[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
 
 More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).
 
@@ -559,9 +561,11 @@ Two common Windows issues:
 
 - Your npm global bin folder is not on PATH.
 - Check the path:
+
   ```powershell
   npm config get prefix
   ```
+
 - Ensure `<prefix>\\bin` is on PATH (on most systems it is `%AppData%\\npm`).
 - Close and reopen PowerShell after updating PATH.
 
@@ -988,7 +992,7 @@ Advantages:
 - **Always-on Gateway** (run on a VPS, interact from anywhere)
 - **Nodes** for local browser/screen/camera/exec
 
-Showcase: https://openclaw.ai/showcase
+Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)
 
 ## Skills and automation
 
@@ -1046,7 +1050,7 @@ Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-v
 ### How do I install skills on Linux
 
 Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.
-Browse skills at https://clawhub.com.
+Browse skills at [https://clawhub.com](https://clawhub.com).
 
 Install the ClawHub CLI (pick one package manager):
 
@@ -1085,13 +1089,16 @@ Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Co
 Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
 
 1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):
+
    ```bash
    #!/usr/bin/env bash
    set -euo pipefail
    exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
    ```
+
 2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).
 3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:
+
    ```markdown
    ---
    name: apple-notes
@@ -1099,6 +1106,7 @@ Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wra
    metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
    ---
    ```
+
 4. Start a new session so the skills snapshot refreshes.
 
 ### Do you have a Notion or HeyGen integration
@@ -1473,6 +1481,7 @@ Typical setup:
 4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)
    so it can register as a node.
 5. Approve the node on the Gateway:
+
    ```bash
    openclaw nodes pending
    openclaw nodes approve <requestId>
@@ -1610,10 +1619,12 @@ This sets your workspace and restricts who can trigger the bot.
 Minimal steps:
 
 1. **Install + login on the VPS**
+
    ```bash
    curl -fsSL https://tailscale.com/install.sh | sh
    sudo tailscale up
    ```
+
 2. **Install + login on your Mac**
    - Use the Tailscale app and sign in to the same tailnet.
 3. **Enable MagicDNS (recommended)**
@@ -1640,6 +1651,7 @@ Recommended setup:
 2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
    The app will tunnel the Gateway port and connect as a node.
 3. **Approve the node** on the gateway:
+
    ```bash
    openclaw nodes pending
    openclaw nodes approve <requestId>
@@ -1702,9 +1714,11 @@ If the Gateway runs as a service (launchd/systemd), it won't inherit your shell
 environment. Fix by doing one of these:
 
 1. Put the token in `~/.openclaw/.env`:
+
    ```
    COPILOT_GITHUB_TOKEN=...
    ```
+
 2. Or enable shell import (`env.shellEnv.enabled: true`).
 3. Or add it to your config `env` block (applies only if missing).
 
@@ -1801,6 +1815,7 @@ Use one of these:
   or `/compact <instructions>` to guide the summary.
 
 - **Reset** (fresh session ID for the same chat key):
+
   ```
   /new
   /reset
@@ -2071,9 +2086,11 @@ Fix checklist:
 3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.1` or
    `minimax/MiniMax-M2.1-lightning`.
 4. Run:
+
    ```bash
    openclaw models list
    ```
+
    and pick from the list (or `/model list` in chat).
 
 See [MiniMax](/providers/minimax) and [Models](/concepts/models).
@@ -2238,9 +2255,11 @@ can't find it in its auth store.
 - **If you want to use an API key instead**
   - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.
   - Clear any pinned order that forces a missing profile:
+
     ```bash
     openclaw models auth order clear --provider anthropic
     ```
+
 - **Confirm you're running commands on the gateway host**
   - In remote mode, auth profiles live on the gateway machine, not your laptop.
 

docs/help/submitting-a-pr.md

@@ -3,212 +3,396 @@ summary: "How to submit a high signal PR"
 title: "Submitting a PR"
 ---
 
-# Submitting a PR
-
-Good PRs make it easy for reviewers to understand intent, verify behavior, and land changes safely. This guide focuses on high-signal, low-noise submissions that work well with both human review and LLM-assisted review.
+Good PRs are easy to review: reviewers should quickly know the intent, verify behavior, and land changes safely. This guide covers concise, high-signal submissions for human and LLM review.
 
 ## What makes a good PR
 
-- [ ] Clear intent: explain the problem, why it matters, and what the change does.
-- [ ] Tight scope: keep changes focused and avoid drive-by refactors.
-- [ ] Behavior summary: call out user-visible changes, config changes, and defaults.
-- [ ] Tests: list what ran, what was skipped, and why.
-- [ ] Evidence: include logs, screenshots, or short recordings for UI or workflows.
-- [ ] Code word: include “lobster-biscuit” somewhere in the PR description to confirm you read this guide.
-- [ ] Baseline checks: run the relevant `pnpm` commands for this repo and fix failures before opening the PR.
-- [ ] Due diligence: search the codebase for existing functionality and check GitHub for related issues or prior fixes.
-- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
-- [ ] Title guidance: use a verb + scope + outcome (for example `Docs: add PR and issue templates`).
+- [ ] Explain the problem, why it matters, and the change.
+- [ ] Keep changes focused. Avoid broad refactors.
+- [ ] Summarize user-visible/config/default changes.
+- [ ] List test coverage, skips, and reasons.
+- [ ] Add evidence: logs, screenshots, or recordings (UI/UX).
+- [ ] Code word: put “lobster-biscuit” in the PR description if you read this guide.
+- [ ] Run/fix relevant `pnpm` commands before creating PR.
+- [ ] Search codebase and GitHub for related functionality/issues/fixes.
+- [ ] Base claims on evidence or observation.
+- [ ] Good title: verb + scope + outcome (e.g., `Docs: add PR and issue templates`).
 
-Guideline: concision > grammar. Be terse if it makes review faster.
+Be concise; concise review > grammar. Omit any non-applicable sections.
 
-Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
+### Baseline validation commands (run/fix failures for your change)
 
 - `pnpm lint`
 - `pnpm check`
 - `pnpm build`
 - `pnpm test`
-- If you touch protocol code: `pnpm protocol:check`
+- Protocol changes: `pnpm protocol:check`
 
 ## Progressive disclosure
 
-Use a short top section, then deeper details as needed.
+- Top: summary/intent
+- Next: changes/risks
+- Next: test/verification
+- Last: implementation/evidence
 
-1. Summary and intent
-2. Behavior changes and risks
-3. Tests and verification
-4. Implementation details and evidence
+## Common PR types: specifics
 
-This keeps review fast while preserving deep context for anyone who needs it.
-
-## Common PR types and expectations
-
-- [ ] Fix: include clear repro, root cause summary, and verification steps.
-- [ ] Feature: include use cases, behavior changes, and screenshots or demos when UI is involved.
-- [ ] Refactor: explicitly state “no behavior change” and list what moved or was simplified.
-- [ ] Chore/Maintenance: note why it matters (build time, CI stability, dependency hygiene).
-- [ ] Docs: include before/after context and link to the updated page. Run `pnpm format`.
-- [ ] Test: explain the gap it covers and how it prevents regressions.
-- [ ] Perf: include baseline and after metrics, plus how they were measured.
-- [ ] UX/UI: include screenshots or short recordings and any accessibility impact.
-- [ ] Infra/Build: call out affected environments and how to validate.
-- [ ] Security: include threat or risk summary, repro steps, and verification plan. Avoid sensitive data in public logs.
-- [ ] Security: keep reports grounded in reality; avoid speculative claims.
+- [ ] Fix: Add repro, root cause, verification.
+- [ ] Feature: Add use cases, behavior/demos/screenshots (UI).
+- [ ] Refactor: State "no behavior change", list what moved/simplified.
+- [ ] Chore: State why (e.g., build time, CI, dependencies).
+- [ ] Docs: Before/after context, link updated page, run `pnpm format`.
+- [ ] Test: What gap is covered; how it prevents regressions.
+- [ ] Perf: Add before/after metrics, and how measured.
+- [ ] UX/UI: Screenshots/video, note accessibility impact.
+- [ ] Infra/Build: Environments/validation.
+- [ ] Security: Summarize risk, repro, verification, no sensitive data. Grounded claims only.
 
 ## Checklist
 
-- [ ] Problem and intent are clear
-- [ ] Scope is focused
-- [ ] Behavior changes are listed
-- [ ] Tests are listed with results
-- [ ] Evidence is attached when needed
-- [ ] No secrets or private data
-- [ ] Grounded in reality: no guesswork or invented context.
+- [ ] Clear problem/intent
+- [ ] Focused scope
+- [ ] List behavior changes
+- [ ] List and result of tests
+- [ ] Manual test steps (when applicable)
+- [ ] No secrets/private data
+- [ ] Evidence-based
 
-## Template
+## General PR Template
 
 ```md
-## Summary
+#### Summary
 
-## Behavior Changes
+#### Behavior Changes
 
-## Codebase and GitHub Search
+#### Codebase and GitHub Search
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort (self-reported):
+- Agent notes (optional, cite evidence):
 ```
 
-## Templates by PR type
+## PR Type templates (replace with your type)
 
 ### Fix
 
 ```md
-## Summary
+#### Summary
 
-## Repro Steps
+#### Repro Steps
 
-## Root Cause
+#### Root Cause
 
-## Behavior Changes
+#### Behavior Changes
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Feature
 
 ```md
-## Summary
+#### Summary
 
-## Use Cases
+#### Use Cases
 
-## Behavior Changes
+#### Behavior Changes
 
-## Existing Functionality Check
+#### Existing Functionality Check
 
-I searched the codebase for existing functionality before implementing this.
+- [ ] I searched the codebase for existing functionality.
+      Searches performed (1-3 bullets):
+  -
+  -
 
-## Tests
+#### Tests
 
-## Evidence
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Refactor
 
 ```md
-## Summary
+#### Summary
 
-## Scope
+#### Scope
 
-## No Behavior Change Statement
+#### No Behavior Change Statement
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Chore/Maintenance
 
 ```md
-## Summary
+#### Summary
 
-## Why This Matters
+#### Why This Matters
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Docs
 
 ```md
-## Summary
+#### Summary
 
-## Pages Updated
+#### Pages Updated
 
-## Screenshots or Before/After
+#### Before/After
 
-## Formatting
+#### Formatting
 
 pnpm format
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Test
 
 ```md
-## Summary
+#### Summary
 
-## Gap Covered
+#### Gap Covered
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Perf
 
 ```md
-## Summary
+#### Summary
 
-## Baseline
+#### Baseline
 
-## After
+#### After
 
-## Measurement Method
+#### Measurement Method
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### UX/UI
 
 ```md
-## Summary
+#### Summary
 
-## Screenshots or Video
+#### Screenshots or Video
 
-## Accessibility Impact
+#### Accessibility Impact
 
-## Tests
+#### Tests
+
+#### Manual Testing
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2. **Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Infra/Build
 
 ```md
-## Summary
+#### Summary
 
-## Environments Affected
+#### Environments Affected
 
-## Validation Steps
+#### Validation Steps
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```
 
 ### Security
 
 ```md
-## Summary
+#### Summary
 
-## Risk Summary
+#### Risk Summary
 
-## Repro Steps
+#### Repro Steps
 
-## Mitigation or Fix
+#### Mitigation or Fix
 
-## Verification
+#### Verification
 
-## Tests
+#### Tests
+
+#### Manual Testing (omit if N/A)
+
+### Prerequisites
+
+-
+
+### Steps
+
+1.
+2.
+
+#### Evidence (omit if N/A)
+
+**Sign-Off**
+
+- Models used:
+- Submitter effort:
+- Agent notes:
 ```

docs/help/submitting-an-issue.md

@@ -1,165 +1,152 @@
 ---
-summary: "How to file high signal issues and bug reports"
+summary: "Filing high-signal issues and bug reports"
 title: "Submitting an Issue"
 ---
 
-# Submitting an Issue
+## Submitting an Issue
 
-Good issues make it easy to reproduce, diagnose, and fix problems quickly. This guide covers what to include for bugs, regressions, and feature gaps.
+Clear, concise issues speed up diagnosis and fixes. Include the following for bugs, regressions, or feature gaps:
 
-## What makes a good issue
+### What to include
 
-- [ ] Clear title: include the area and the symptom.
-- [ ] Repro steps: minimal steps that consistently reproduce the issue.
-- [ ] Expected vs actual: what you thought would happen and what did.
-- [ ] Impact: who is affected and how severe the problem is.
-- [ ] Environment: OS, runtime, versions, and relevant config.
-- [ ] Evidence: logs, screenshots, or recordings (redacted; prefer non-PII data).
-- [ ] Scope: note if it is new, regression, or long-standing.
-- [ ] Code word: include “lobster-biscuit” somewhere in the issue description to confirm you read this guide.
-- [ ] Due diligence: search the codebase for existing functionality and check GitHub to see if the issue is already filed or fixed.
-- [ ] I searched for existing and recently closed issues/PRs.
-- [ ] For security reports: confirmed it has not already been fixed or addressed recently.
-- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+- [ ] Title: area & symptom
+- [ ] Minimal repro steps
+- [ ] Expected vs actual
+- [ ] Impact & severity
+- [ ] Environment: OS, runtime, versions, config
+- [ ] Evidence: redacted logs, screenshots (non-PII)
+- [ ] Scope: new, regression, or longstanding
+- [ ] Code word: lobster-biscuit in your issue
+- [ ] Searched codebase & GitHub for existing issue
+- [ ] Confirmed not recently fixed/addressed (esp. security)
+- [ ] Claims backed by evidence or repro
 
-Guideline: concision > grammar. Be terse if it makes review faster.
+Be brief. Terseness > perfect grammar.
 
-Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
+Validation (run/fix before PR):
 
 - `pnpm lint`
 - `pnpm check`
 - `pnpm build`
 - `pnpm test`
-- If you touch protocol code: `pnpm protocol:check`
+- If protocol code: `pnpm protocol:check`
 
-## Templates
+### Templates
 
-### Bug report
+#### Bug report
 
 ```md
-## Bug report checklist
-
-- [ ] Minimal repro steps
+- [ ] Minimal repro
 - [ ] Expected vs actual
-- [ ] Versions and environment
-- [ ] Affected channels and where it does not reproduce
-- [ ] Logs or screenshots
-- [ ] Evidence is redacted and non-PII where possible
-- [ ] Impact and severity
-- [ ] Any known workarounds
+- [ ] Environment
+- [ ] Affected channels, where not seen
+- [ ] Logs/screenshots (redacted)
+- [ ] Impact/severity
+- [ ] Workarounds
 
-## Summary
+### Summary
 
-## Repro Steps
+### Repro Steps
 
-## Expected
+### Expected
 
-## Actual
+### Actual
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 
-## Workarounds
+### Workarounds
 ```
 
-### Security issue
+#### Security issue
 
 ```md
-## Summary
+### Summary
 
-## Impact
+### Impact
 
-## Affected Versions
+### Versions
 
-## Repro Steps (if safe to share)
+### Repro Steps (safe to share)
 
-## Mitigation or Workaround
+### Mitigation/workaround
 
-## Evidence (redacted)
+### Evidence (redacted)
 ```
 
-Security note: avoid posting secrets or exploit details in public issues. If the report is sensitive, keep repro details minimal and ask for a private disclosure path.
+_Avoid secrets/exploit details in public. For sensitive issues, minimize detail and request private disclosure._
 
-### Regression report
+#### Regression report
 
 ```md
-## Summary
+### Summary
 
-## Last Known Good
+### Last Known Good
 
-## First Known Bad
+### First Known Bad
 
-## Repro Steps
+### Repro Steps
 
-## Expected
+### Expected
 
-## Actual
+### Actual
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 ```
 
-### Feature request
+#### Feature request
 
 ```md
-## Summary
+### Summary
 
-## Problem
+### Problem
 
-## Proposed Solution
+### Proposed Solution
 
-## Alternatives Considered
+### Alternatives
 
-## Impact
+### Impact
 
-## Evidence or Examples
+### Evidence/examples
 ```
 
-### Enhancement request
+#### Enhancement
 
 ```md
-## Summary
+### Summary
 
-## Current Behavior
+### Current vs Desired Behavior
 
-## Desired Behavior
+### Rationale
 
-## Why This Matters
+### Alternatives
 
-## Alternatives Considered
-
-## Evidence or Examples
+### Evidence/examples
 ```
 
-### Investigation request
+#### Investigation
 
 ```md
-## Summary
+### Summary
 
-## Symptoms
+### Symptoms
 
-## What Was Tried
+### What Was Tried
 
-## Environment
+### Environment
 
-## Logs or Evidence
+### Logs/Evidence
 
-## Impact
+### Impact
 ```
 
-## If you are submitting a fix PR
+### Submitting a fix PR
 
-Creating a separate issue first is optional. If you skip it, include the relevant details in the PR description.
-
-- Keep the PR focused on the issue.
-- Include the issue number in the PR description.
-- Add tests when possible, or explain why they are not feasible.
-- Note any behavior changes and risks.
-- Include redacted logs, screenshots, or videos that validate the fix.
-- Run relevant `pnpm` validation commands and report results when appropriate.
+Issue before PR is optional. Include details in PR if skipping. Keep the PR focused, note issue number, add tests or explain absence, document behavior changes/risks, include redacted logs/screenshots as proof, and run proper validation before submitting.

docs/help/troubleshooting.md

@@ -1,98 +1,265 @@
 ---
-summary: "Troubleshooting hub: symptoms → checks → fixes"
+summary: "Symptom first troubleshooting hub for OpenClaw"
 read_when:
-  - You see an error and want the fix path
-  - The installer says “success” but the CLI doesn’t work
+  - OpenClaw is not working and you need the fastest path to a fix
+  - You want a triage flow before diving into deep runbooks
 title: "Troubleshooting"
 ---
 
 # Troubleshooting
 
+If you only have 2 minutes, use this page as a triage front door.
+
 ## First 60 seconds
 
-Run these in order:
+Run this exact ladder in order:
 
 ```bash
 openclaw status
 openclaw status --all
 openclaw gateway probe
-openclaw logs --follow
+openclaw gateway status
 openclaw doctor
+openclaw channels status --probe
+openclaw logs --follow
 ```
 
-If the gateway is reachable, deep probes:
+Good output in one line:
 
-```bash
-openclaw status --deep
+- `openclaw status` → shows configured channels and no obvious auth errors.
+- `openclaw status --all` → full report is present and shareable.
+- `openclaw gateway probe` → expected gateway target is reachable.
+- `openclaw gateway status` → `Runtime: running` and `RPC probe: ok`.
+- `openclaw doctor` → no blocking config/service errors.
+- `openclaw channels status --probe` → channels report `connected` or `ready`.
+- `openclaw logs --follow` → steady activity, no repeating fatal errors.
+
+## Decision tree
+
+```mermaid
+flowchart TD
+  A[OpenClaw is not working] --> B{What breaks first}
+  B --> C[No replies]
+  B --> D[Dashboard or Control UI will not connect]
+  B --> E[Gateway will not start or service not running]
+  B --> F[Channel connects but messages do not flow]
+  B --> G[Cron or heartbeat did not fire or did not deliver]
+  B --> H[Node is paired but camera canvas screen exec fails]
+  B --> I[Browser tool fails]
+
+  C --> C1[/No replies section/]
+  D --> D1[/Control UI section/]
+  E --> E1[/Gateway section/]
+  F --> F1[/Channel flow section/]
+  G --> G1[/Automation section/]
+  H --> H1[/Node tools section/]
+  I --> I1[/Browser section/]
 ```
 
-## Common “it broke” cases
+<AccordionGroup>
+  <Accordion title="No replies">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw channels status --probe
+    openclaw pairing list <channel>
+    openclaw logs --follow
+    ```
 
-### `openclaw: command not found`
+    Good output looks like:
 
-Almost always a Node/npm PATH issue. Start here:
+    - `Runtime: running`
+    - `RPC probe: ok`
+    - Your channel shows connected/ready in `channels status --probe`
+    - Sender appears approved (or DM policy is open/allowlist)
 
-- [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)
+    Common log signatures:
 
-### Installer fails (or you need full logs)
+    - `drop guild message (mention required` → mention gating blocked the message in Discord.
+    - `pairing request` → sender is unapproved and waiting for DM pairing approval.
+    - `blocked` / `allowlist` in channel logs → sender, room, or group is filtered.
 
-Re-run the installer in verbose mode to see the full trace and npm output:
+    Deep pages:
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
-```
+    - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
+    - [/channels/troubleshooting](/channels/troubleshooting)
+    - [/start/pairing](/start/pairing)
 
-For beta installs:
+  </Accordion>
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
-```
+  <Accordion title="Dashboard or Control UI will not connect">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-You can also set `OPENCLAW_VERBOSE=1` instead of the flag.
+    Good output looks like:
 
-### Gateway “unauthorized”, can’t connect, or keeps reconnecting
+    - `Dashboard: http://...` is shown in `openclaw gateway status`
+    - `RPC probe: ok`
+    - No auth loop in logs
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Gateway authentication](/gateway/authentication)
+    Common log signatures:
 
-### Control UI fails on HTTP (device identity required)
+    - `device identity required` → HTTP/non-secure context cannot complete device auth.
+    - `unauthorized` / reconnect loop → wrong token/password or auth mode mismatch.
+    - `gateway connect failed:` → UI is targeting the wrong URL/port or unreachable gateway.
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Control UI](/web/control-ui#insecure-http)
+    Deep pages:
 
-### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)
+    - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+    - [/web/control-ui](/web/control-ui)
+    - [/gateway/authentication](/gateway/authentication)
 
-Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.
-Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.
+  </Accordion>
 
-- Xfinity Advanced Security help: https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
-- Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering
+  <Accordion title="Gateway will not start or service installed but not running">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-### Service says running, but RPC probe fails
+    Good output looks like:
 
-- [Gateway troubleshooting](/gateway/troubleshooting)
-- [Background process / service](/gateway/background-process)
+    - `Service: ... (loaded)`
+    - `Runtime: running`
+    - `RPC probe: ok`
 
-### Model/auth failures (rate limit, billing, “all models failed”)
+    Common log signatures:
 
-- [Models](/cli/models)
-- [OAuth / auth concepts](/concepts/oauth)
+    - `Gateway start blocked: set gateway.mode=local` → gateway mode is unset/remote.
+    - `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
+    - `another gateway instance is already listening` or `EADDRINUSE` → port already taken.
 
-### `/model` says `model not allowed`
+    Deep pages:
 
-This usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty,
-only those provider/model keys can be selected.
+    - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
+    - [/gateway/background-process](/gateway/background-process)
+    - [/gateway/configuration](/gateway/configuration)
 
-- Check the allowlist: `openclaw config get agents.defaults.models`
-- Add the model you want (or clear the allowlist) and retry `/model`
-- Use `/models` to browse the allowed providers/models
+  </Accordion>
 
-### When filing an issue
+  <Accordion title="Channel connects but messages do not flow">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw logs --follow
+    openclaw doctor
+    openclaw channels status --probe
+    ```
 
-Paste a safe report:
+    Good output looks like:
 
-```bash
-openclaw status --all
-```
+    - Channel transport is connected.
+    - Pairing/allowlist checks pass.
+    - Mentions are detected where required.
 
-If you can, include the relevant log tail from `openclaw logs --follow`.
+    Common log signatures:
+
+    - `mention required` → group mention gating blocked processing.
+    - `pairing` / `pending` → DM sender is not approved yet.
+    - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel permission token issue.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
+    - [/channels/troubleshooting](/channels/troubleshooting)
+
+  </Accordion>
+
+  <Accordion title="Cron or heartbeat did not fire or did not deliver">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw cron status
+    openclaw cron list
+    openclaw cron runs --id <jobId> --limit 20
+    openclaw logs --follow
+    ```
+
+    Good output looks like:
+
+    - `cron.status` shows enabled with a next wake.
+    - `cron runs` shows recent `ok` entries.
+    - Heartbeat is enabled and not outside active hours.
+
+    Common log signatures:
+
+    - `cron: scheduler disabled; jobs will not run automatically` → cron is disabled.
+    - `heartbeat skipped` with `reason=quiet-hours` → outside configured active hours.
+    - `requests-in-flight` → main lane busy; heartbeat wake was deferred.
+    - `unknown accountId` → heartbeat delivery target account does not exist.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
+    - [/automation/troubleshooting](/automation/troubleshooting)
+    - [/gateway/heartbeat](/gateway/heartbeat)
+
+  </Accordion>
+
+  <Accordion title="Node is paired but tool fails camera canvas screen exec">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw nodes status
+    openclaw nodes describe --node <idOrNameOrIp>
+    openclaw logs --follow
+    ```
+
+    Good output looks like:
+
+    - Node is listed as connected and paired for role `node`.
+    - Capability exists for the command you are invoking.
+    - Permission state is granted for the tool.
+
+    Common log signatures:
+
+    - `NODE_BACKGROUND_UNAVAILABLE` → bring node app to foreground.
+    - `*_PERMISSION_REQUIRED` → OS permission was denied/missing.
+    - `SYSTEM_RUN_DENIED: approval required` → exec approval is pending.
+    - `SYSTEM_RUN_DENIED: allowlist miss` → command not on exec allowlist.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
+    - [/nodes/troubleshooting](/nodes/troubleshooting)
+    - [/tools/exec-approvals](/tools/exec-approvals)
+
+  </Accordion>
+
+  <Accordion title="Browser tool fails">
+    ```bash
+    openclaw status
+    openclaw gateway status
+    openclaw browser status
+    openclaw logs --follow
+    openclaw doctor
+    ```
+
+    Good output looks like:
+
+    - Browser status shows `running: true` and a chosen browser/profile.
+    - `openclaw` profile starts or `chrome` relay has an attached tab.
+
+    Common log signatures:
+
+    - `Failed to start Chrome CDP on port` → local browser launch failed.
+    - `browser.executablePath not found` → configured binary path is wrong.
+    - `Chrome extension relay is running, but no tab is connected` → extension not attached.
+    - `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target.
+
+    Deep pages:
+
+    - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
+    - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
+    - [/tools/chrome-extension](/tools/chrome-extension)
+
+  </Accordion>
+</AccordionGroup>

docs/hooks.md

@@ -787,6 +787,7 @@ Session reset
    ```
 
 3. List all discovered hooks:
+
    ```bash
    openclaw hooks list
    ```
@@ -818,6 +819,7 @@ Look for missing:
 2. Restart your gateway process so hooks reload.
 
 3. Check gateway logs for errors:
+
    ```bash
    ./scripts/clawlog.sh | grep hook
    ```
@@ -892,6 +894,7 @@ node -e "import('./path/to/handler.ts').then(console.log)"
    ```
 
 4. Verify and restart your gateway process:
+
    ```bash
    openclaw hooks list
    # Should show: 🎯 my-hook ✓

docs/index.md

@@ -120,7 +120,7 @@ Need the full install and dev setup? See [Quick start](/start/quickstart).
 
 Open the browser Control UI after the Gateway starts.
 
-- Local default: http://127.0.0.1:18789/
+- Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/)
 - Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
 
 <p align="center">

docs/install/gcp.md

@@ -69,7 +69,7 @@ For the generic Docker flow, see [Docker](/install/docker).
 
 **Option A: gcloud CLI** (recommended for automation)
 
-Install from https://cloud.google.com/sdk/docs/install
+Install from [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
 
 Initialize and authenticate:
 
@@ -80,7 +80,7 @@ gcloud auth login
 
 **Option B: Cloud Console**
 
-All steps can be done via the web UI at https://console.cloud.google.com
+All steps can be done via the web UI at [https://console.cloud.google.com](https://console.cloud.google.com)
 
 ---
 
@@ -93,7 +93,7 @@ gcloud projects create my-openclaw-project --name="OpenClaw Gateway"
 gcloud config set project my-openclaw-project
 ```
 
-Enable billing at https://console.cloud.google.com/billing (required for Compute Engine).
+Enable billing at [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (required for Compute Engine).
 
 Enable the Compute Engine API:
 
@@ -484,6 +484,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim
    ```
 
 2. Grant Compute Instance Admin role (or narrower custom role):
+
    ```bash
    gcloud projects add-iam-policy-binding my-openclaw-project \
      --member="serviceAccount:openclaw-deploy@my-openclaw-project.iam.gserviceaccount.com" \
@@ -492,7 +493,7 @@ For automation or CI/CD pipelines, create a dedicated service account with minim
 
 Avoid using the Owner role for automation. Use the principle of least privilege.
 
-See https://cloud.google.com/iam/docs/understanding-roles for IAM role details.
+See [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) for IAM role details.
 
 ---
 

docs/install/installer.md

@@ -1,5 +1,5 @@
 ---
-summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
+summary: "How the installer scripts work (install.sh, install-cli.sh, install.ps1), flags, and automation"
 read_when:
   - You want to understand `openclaw.ai/install.sh`
   - You want to automate installs (CI / headless)
@@ -9,153 +9,377 @@ title: "Installer Internals"
 
 # Installer internals
 
-OpenClaw ships two installer scripts (served from `openclaw.ai`):
+OpenClaw ships three installer scripts, served from `openclaw.ai`.
 
-- `https://openclaw.ai/install.sh` - "recommended" installer (global npm install by default; can also install from a GitHub checkout)
-- `https://openclaw.ai/install-cli.sh` - non-root-friendly CLI installer (installs into a prefix with its own Node)
-- `https://openclaw.ai/install.ps1` - Windows PowerShell installer (npm by default; optional git install)
+| Script                             | Platform             | What it does                                                                                 |
+| ---------------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
+| [`install.sh`](#installsh)         | macOS / Linux / WSL  | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. |
+| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | Installs Node + OpenClaw into a local prefix (`~/.openclaw`). No root required.              |
+| [`install.ps1`](#installps1)       | Windows (PowerShell) | Installs Node if needed, installs OpenClaw via npm (default) or git, and can run onboarding. |
 
-To see the current flags/behavior, run:
+## Quick commands
 
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
-```
+<Tabs>
+  <Tab title="install.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
 
-Windows (PowerShell) help:
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
+    ```
 
-```powershell
-& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
-```
+  </Tab>
+  <Tab title="install-cli.sh">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
+    ```
 
-If the installer completes but `openclaw` is not found in a new terminal, it's usually a Node/npm PATH issue. See: [Node.js](/install/node#troubleshooting).
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
+    ```
 
-## Flags and environment variables
+  </Tab>
+  <Tab title="install.ps1">
+    ```powershell
+    iwr -useb https://openclaw.ai/install.ps1 | iex
+    ```
 
-### CLI flags (install.sh)
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
+    ```
 
-| Flag                        | Description                                      |
-| --------------------------- | ------------------------------------------------ |
-| `--install-method npm\|git` | Choose install method (default: `npm`)           |
-| `--git-dir <path>`          | Source checkout location (default: `~/openclaw`) |
-| `--no-git-update`           | Skip `git pull` when using an existing checkout  |
-| `--no-prompt`               | Disable prompts (required in CI/automation)      |
-| `--dry-run`                 | Print what would happen; make no changes         |
-| `--no-onboard`              | Skip onboarding after install                    |
+  </Tab>
+</Tabs>
 
-### PowerShell flags (install.ps1)
+<Note>
+If install succeeds but `openclaw` is not found in a new terminal, see [Node.js troubleshooting](/install/node#troubleshooting).
+</Note>
 
-| Flag                      | Description                                     |
-| ------------------------- | ----------------------------------------------- |
-| `-InstallMethod npm\|git` | Choose install method (default: `npm`)          |
-| `-GitDir <path>`          | Source checkout location                        |
-| `-NoOnboard`              | Skip onboarding after install                   |
-| `-NoGitUpdate`            | Skip `git pull` when using an existing checkout |
-| `-DryRun`                 | Print what would happen; make no changes        |
-| `-Tag <tag>`              | npm dist-tag to install (default: `latest`)     |
+---
 
-### Environment variables
+## install.sh
 
-Equivalent env vars (useful for CI/automation):
+<Tip>
+Recommended for most interactive installs on macOS/Linux/WSL.
+</Tip>
 
-| Variable                           | Description                                                  |
-| ---------------------------------- | ------------------------------------------------------------ |
-| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method                                               |
-| `OPENCLAW_GIT_DIR=<path>`          | Source checkout location                                     |
-| `OPENCLAW_GIT_UPDATE=0\|1`         | Toggle git pull                                              |
-| `OPENCLAW_NO_PROMPT=1`             | Disable prompts                                              |
-| `OPENCLAW_DRY_RUN=1`               | Dry run mode                                                 |
-| `OPENCLAW_NO_ONBOARD=1`            | Skip onboarding                                              |
-| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Avoid `sharp` building against system libvips (default: `1`) |
+### Flow (install.sh)
 
-## install.sh (recommended)
+<Steps>
+  <Step title="Detect OS">
+    Supports macOS and Linux (including WSL). If macOS is detected, installs Homebrew if missing.
+  </Step>
+  <Step title="Ensure Node.js 22+">
+    Checks Node version and installs Node 22 if needed (Homebrew on macOS, NodeSource setup scripts on Linux apt/dnf/yum).
+  </Step>
+  <Step title="Ensure Git">
+    Installs Git if missing.
+  </Step>
+  <Step title="Install OpenClaw">
+    - `npm` method (default): global npm install
+    - `git` method: clone/update repo, install deps with pnpm, build, then install wrapper at `~/.local/bin/openclaw`
+  </Step>
+  <Step title="Post-install tasks">
+    - Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort)
+    - Attempts onboarding when appropriate (TTY available, onboarding not disabled, and bootstrap/config checks pass)
+    - Defaults `SHARP_IGNORE_GLOBAL_LIBVIPS=1`
+  </Step>
+</Steps>
 
-What it does (high level):
+### Source checkout detection
 
-- Detect OS (macOS / Linux / WSL).
-- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
-- Choose install method:
-  - `npm` (default): `npm install -g openclaw@latest`
-  - `git`: clone/build a source checkout and install a wrapper script
-- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed.
-- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort).
-- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort).
-- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
+If run inside an OpenClaw checkout (`package.json` + `pnpm-workspace.yaml`), the script offers:
 
-If you _want_ `sharp` to link against a globally-installed libvips (or you're debugging), set:
+- use checkout (`git`), or
+- use global install (`npm`)
 
-```bash
-SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
-```
+If no TTY is available and no install method is set, it defaults to `npm` and warns.
 
-### Discoverability / "git install" prompt
+The script exits with code `2` for invalid method selection or invalid `--install-method` values.
 
-If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
+### Examples (install.sh)
 
-- update and use this checkout (`git`)
-- or migrate to the global npm install (`npm`)
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="Skip onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
+    ```
+  </Tab>
+</Tabs>
 
-In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`.
+<AccordionGroup>
+  <Accordion title="Flags reference">
 
-### Why Git is needed
+| Flag                            | Description                                                |
+| ------------------------------- | ---------------------------------------------------------- |
+| `--install-method npm\|git`     | Choose install method (default: `npm`). Alias: `--method`  |
+| `--npm`                         | Shortcut for npm method                                    |
+| `--git`                         | Shortcut for git method. Alias: `--github`                 |
+| `--version <version\|dist-tag>` | npm version or dist-tag (default: `latest`)                |
+| `--beta`                        | Use beta dist-tag if available, else fallback to `latest`  |
+| `--git-dir <path>`              | Checkout directory (default: `~/openclaw`). Alias: `--dir` |
+| `--no-git-update`               | Skip `git pull` for existing checkout                      |
+| `--no-prompt`                   | Disable prompts                                            |
+| `--no-onboard`                  | Skip onboarding                                            |
+| `--onboard`                     | Enable onboarding                                          |
+| `--dry-run`                     | Print actions without applying changes                     |
+| `--verbose`                     | Enable debug output (`set -x`, npm notice-level logs)      |
+| `--help`                        | Show usage (`-h`)                                          |
 
-Git is required for the `--install-method git` path (clone / pull).
+  </Accordion>
 
-For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
+  <Accordion title="Environment variables reference">
 
-### Why npm hits `EACCES` on fresh Linux
+| Variable                                    | Description                                   |
+| ------------------------------------------- | --------------------------------------------- |
+| `OPENCLAW_INSTALL_METHOD=git\|npm`          | Install method                                |
+| `OPENCLAW_VERSION=latest\|next\|<semver>`   | npm version or dist-tag                       |
+| `OPENCLAW_BETA=0\|1`                        | Use beta if available                         |
+| `OPENCLAW_GIT_DIR=<path>`                   | Checkout directory                            |
+| `OPENCLAW_GIT_UPDATE=0\|1`                  | Toggle git updates                            |
+| `OPENCLAW_NO_PROMPT=1`                      | Disable prompts                               |
+| `OPENCLAW_NO_ONBOARD=1`                     | Skip onboarding                               |
+| `OPENCLAW_DRY_RUN=1`                        | Dry run mode                                  |
+| `OPENCLAW_VERBOSE=1`                        | Debug mode                                    |
+| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                 |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`) |
 
-On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
+  </Accordion>
+</AccordionGroup>
 
-`install.sh` mitigates this by switching the prefix to:
+---
 
-- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
+## install-cli.sh
 
-## install-cli.sh (non-root CLI installer)
+<Info>
+Designed for environments where you want everything under a local prefix (default `~/.openclaw`) and no system Node dependency.
+</Info>
 
-This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don't want to touch the system Node/npm.
+### Flow (install-cli.sh)
 
-Help:
+<Steps>
+  <Step title="Install local Node runtime">
+    Downloads Node tarball (default `22.22.0`) to `<prefix>/tools/node-v<version>` and verifies SHA-256.
+  </Step>
+  <Step title="Ensure Git">
+    If Git is missing, attempts install via apt/dnf/yum on Linux or Homebrew on macOS.
+  </Step>
+  <Step title="Install OpenClaw under prefix">
+    Installs with npm using `--prefix <prefix>`, then writes wrapper to `<prefix>/bin/openclaw`.
+  </Step>
+</Steps>
 
-```bash
-curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
-```
+### Examples (install-cli.sh)
 
-## install.ps1 (Windows PowerShell)
+<Tabs>
+  <Tab title="Default">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
+    ```
+  </Tab>
+  <Tab title="Custom prefix + version">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
+    ```
+  </Tab>
+  <Tab title="Automation JSON output">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
+    ```
+  </Tab>
+  <Tab title="Run onboarding">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
+    ```
+  </Tab>
+</Tabs>
 
-What it does (high level):
+<AccordionGroup>
+  <Accordion title="Flags reference">
 
-- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
-- Choose install method:
-  - `npm` (default): `npm install -g openclaw@latest`
-  - `git`: clone/build a source checkout and install a wrapper script
-- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
+| Flag                   | Description                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `--prefix <path>`      | Install prefix (default: `~/.openclaw`)                                         |
+| `--version <ver>`      | OpenClaw version or dist-tag (default: `latest`)                                |
+| `--node-version <ver>` | Node version (default: `22.22.0`)                                               |
+| `--json`               | Emit NDJSON events                                                              |
+| `--onboard`            | Run `openclaw onboard` after install                                            |
+| `--no-onboard`         | Skip onboarding (default)                                                       |
+| `--set-npm-prefix`     | On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable |
+| `--help`               | Show usage (`-h`)                                                               |
 
-Examples:
+  </Accordion>
 
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex
-```
+  <Accordion title="Environment variables reference">
 
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
-```
+| Variable                                    | Description                                                                       |
+| ------------------------------------------- | --------------------------------------------------------------------------------- |
+| `OPENCLAW_PREFIX=<path>`                    | Install prefix                                                                    |
+| `OPENCLAW_VERSION=<ver>`                    | OpenClaw version or dist-tag                                                      |
+| `OPENCLAW_NODE_VERSION=<ver>`               | Node version                                                                      |
+| `OPENCLAW_NO_ONBOARD=1`                     | Skip onboarding                                                                   |
+| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | npm log level                                                                     |
+| `OPENCLAW_GIT_DIR=<path>`                   | Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout) |
+| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`          | Control sharp/libvips behavior (default: `1`)                                     |
 
-```powershell
-iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
-```
+  </Accordion>
+</AccordionGroup>
 
-Environment variables:
+---
 
-- `OPENCLAW_INSTALL_METHOD=git|npm`
-- `OPENCLAW_GIT_DIR=...`
+## install.ps1
 
-Git requirement:
+### Flow (install.ps1)
 
-If you choose `-InstallMethod git` and Git is missing, the installer will print the
-Git for Windows link (`https://git-scm.com/download/win`) and exit.
+<Steps>
+  <Step title="Ensure PowerShell + Windows environment">
+    Requires PowerShell 5+.
+  </Step>
+  <Step title="Ensure Node.js 22+">
+    If missing, attempts install via winget, then Chocolatey, then Scoop.
+  </Step>
+  <Step title="Install OpenClaw">
+    - `npm` method (default): global npm install using selected `-Tag`
+    - `git` method: clone/update repo, install/build with pnpm, and install wrapper at `%USERPROFILE%\.local\bin\openclaw.cmd`
+  </Step>
+  <Step title="Post-install tasks">
+    Adds needed bin directory to user PATH when possible, then runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
+  </Step>
+</Steps>
 
-Common Windows issues:
+### Examples (install.ps1)
 
-- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
-- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use
-  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.
+<Tabs>
+  <Tab title="Default">
+    ```powershell
+    iwr -useb https://openclaw.ai/install.ps1 | iex
+    ```
+  </Tab>
+  <Tab title="Git install">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
+    ```
+  </Tab>
+  <Tab title="Custom git directory">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
+    ```
+  </Tab>
+  <Tab title="Dry run">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
+    ```
+  </Tab>
+</Tabs>
+
+<AccordionGroup>
+  <Accordion title="Flags reference">
+
+| Flag                      | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `-InstallMethod npm\|git` | Install method (default: `npm`)                        |
+| `-Tag <tag>`              | npm dist-tag (default: `latest`)                       |
+| `-GitDir <path>`          | Checkout directory (default: `%USERPROFILE%\openclaw`) |
+| `-NoOnboard`              | Skip onboarding                                        |
+| `-NoGitUpdate`            | Skip `git pull`                                        |
+| `-DryRun`                 | Print actions only                                     |
+
+  </Accordion>
+
+  <Accordion title="Environment variables reference">
+
+| Variable                           | Description        |
+| ---------------------------------- | ------------------ |
+| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method     |
+| `OPENCLAW_GIT_DIR=<path>`          | Checkout directory |
+| `OPENCLAW_NO_ONBOARD=1`            | Skip onboarding    |
+| `OPENCLAW_GIT_UPDATE=0`            | Disable git pull   |
+| `OPENCLAW_DRY_RUN=1`               | Dry run mode       |
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+If `-InstallMethod git` is used and Git is missing, the script exits and prints the Git for Windows link.
+</Note>
+
+---
+
+## CI and automation
+
+Use non-interactive flags/env vars for predictable runs.
+
+<Tabs>
+  <Tab title="install.sh (non-interactive npm)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
+    ```
+  </Tab>
+  <Tab title="install.sh (non-interactive git)">
+    ```bash
+    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
+      curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
+  </Tab>
+  <Tab title="install-cli.sh (JSON)">
+    ```bash
+    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
+    ```
+  </Tab>
+  <Tab title="install.ps1 (skip onboarding)">
+    ```powershell
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+    ```
+  </Tab>
+</Tabs>
+
+---
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Why is Git required?">
+    Git is required for `git` install method. For `npm` installs, Git is still checked/installed to avoid `spawn git ENOENT` failures when dependencies use git URLs.
+  </Accordion>
+
+  <Accordion title="Why does npm hit EACCES on Linux?">
+    Some Linux setups point npm global prefix to root-owned paths. `install.sh` can switch prefix to `~/.npm-global` and append PATH exports to shell rc files (when those files exist).
+  </Accordion>
+
+  <Accordion title="sharp/libvips issues">
+    The scripts default `SHARP_IGNORE_GLOBAL_LIBVIPS=1` to avoid sharp building against system libvips. To override:
+
+    ```bash
+    SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
+    ```
+
+  </Accordion>
+
+  <Accordion title='Windows: "npm error spawn git / ENOENT"'>
+    Install Git for Windows, reopen PowerShell, rerun installer.
+  </Accordion>
+
+  <Accordion title='Windows: "openclaw is not recognized"'>
+    Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell.
+  </Accordion>
+
+  <Accordion title="openclaw not found after install">
+    Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
+  </Accordion>
+</AccordionGroup>

docs/install/northflank.mdx

@@ -45,7 +45,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod
 
 ### Discord bot token
 
-1. Go to https://discord.com/developers/applications
+1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications)
 2. **New Application** → choose a name
 3. **Bot** → **Add Bot**
 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup)

docs/install/railway.mdx

@@ -83,7 +83,7 @@ If Telegram DMs are set to pairing, the setup wizard can approve the pairing cod
 
 ### Discord bot token
 
-1. Go to https://discord.com/developers/applications
+1. Go to [https://discord.com/developers/applications](https://discord.com/developers/applications)
 2. **New Application** → choose a name
 3. **Bot** → **Add Bot**
 4. **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup)

docs/install/render.mdx

@@ -11,13 +11,7 @@ Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yam
 
 ## Deploy with a Render Blueprint
 
-<a
-  href="https://render.com/deploy?repo=https://github.com/openclaw/openclaw"
-  target="_blank"
-  rel="noreferrer"
->
-  Deploy to Render
-</a>
+[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
 
 Clicking this link will:
 

docs/install/updating.md

@@ -24,10 +24,13 @@ Notes:
 
 - Add `--no-onboard` if you don’t want the onboarding wizard to run again.
 - For **source installs**, use:
+
   ```bash
   curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard
   ```
+
   The installer will `git pull --rebase` **only** if the repo is clean.
+
 - For **global installs**, the script uses `npm install -g openclaw@latest` under the hood.
 - Legacy note: `clawdbot` remains available as a compatibility shim.
 
@@ -225,4 +228,4 @@ git pull
 
 - Run `openclaw doctor` again and read the output carefully (it often tells you the fix).
 - Check: [Troubleshooting](/gateway/troubleshooting)
-- Ask in Discord: https://discord.gg/clawd
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)

docs/multi-agent-sandbox-tools.md

@@ -362,6 +362,7 @@ After configuring multi-agent sandbox and tools:
    - Verify the agent cannot use denied tools
 
 4. **Monitor logs:**
+
    ```exec
    tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"
    ```

docs/nodes/index.md

@@ -19,6 +19,7 @@ Notes:
 
 - Nodes are **peripherals**, not gateways. They don’t run the gateway service.
 - Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes.
+- Troubleshooting runbook: [/nodes/troubleshooting](/nodes/troubleshooting)
 
 ## Pairing + status
 

docs/nodes/troubleshooting.md

@@ -0,0 +1,112 @@
+---
+summary: "Troubleshoot node pairing, foreground requirements, permissions, and tool failures"
+read_when:
+  - Node is connected but camera/canvas/screen/exec tools fail
+  - You need the node pairing versus approvals mental model
+title: "Node Troubleshooting"
+---
+
+# Node troubleshooting
+
+Use this page when a node is visible in status but node tools fail.
+
+## Command ladder
+
+```bash
+openclaw status
+openclaw gateway status
+openclaw logs --follow
+openclaw doctor
+openclaw channels status --probe
+```
+
+Then run node specific checks:
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw approvals get --node <idOrNameOrIp>
+```
+
+Healthy signals:
+
+- Node is connected and paired for role `node`.
+- `nodes describe` includes the capability you are calling.
+- Exec approvals show expected mode/allowlist.
+
+## Foreground requirements
+
+`canvas.*`, `camera.*`, and `screen.*` are foreground only on iOS/Android nodes.
+
+Quick check and fix:
+
+```bash
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw nodes canvas snapshot --node <idOrNameOrIp>
+openclaw logs --follow
+```
+
+If you see `NODE_BACKGROUND_UNAVAILABLE`, bring the node app to the foreground and retry.
+
+## Permissions matrix
+
+| Capability                   | iOS                                     | Android                                      | macOS node app                | Typical failure code           |
+| ---------------------------- | --------------------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------ |
+| `camera.snap`, `camera.clip` | Camera (+ mic for clip audio)           | Camera (+ mic for clip audio)                | Camera (+ mic for clip audio) | `*_PERMISSION_REQUIRED`        |
+| `screen.record`              | Screen Recording (+ mic optional)       | Screen capture prompt (+ mic optional)       | Screen Recording              | `*_PERMISSION_REQUIRED`        |
+| `location.get`               | While Using or Always (depends on mode) | Foreground/Background location based on mode | Location permission           | `LOCATION_PERMISSION_REQUIRED` |
+| `system.run`                 | n/a (node host path)                    | n/a (node host path)                         | Exec approvals required       | `SYSTEM_RUN_DENIED`            |
+
+## Pairing versus approvals
+
+These are different gates:
+
+1. **Device pairing**: can this node connect to the gateway?
+2. **Exec approvals**: can this node run a specific shell command?
+
+Quick checks:
+
+```bash
+openclaw devices list
+openclaw nodes status
+openclaw approvals get --node <idOrNameOrIp>
+openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
+```
+
+If pairing is missing, approve the node device first.
+If pairing is fine but `system.run` fails, fix exec approvals/allowlist.
+
+## Common node error codes
+
+- `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground.
+- `CAMERA_DISABLED` → camera toggle disabled in node settings.
+- `*_PERMISSION_REQUIRED` → OS permission missing/denied.
+- `LOCATION_DISABLED` → location mode is off.
+- `LOCATION_PERMISSION_REQUIRED` → requested location mode not granted.
+- `LOCATION_BACKGROUND_UNAVAILABLE` → app is backgrounded but only While Using permission exists.
+- `SYSTEM_RUN_DENIED: approval required` → exec request needs explicit approval.
+- `SYSTEM_RUN_DENIED: allowlist miss` → command blocked by allowlist mode.
+
+## Fast recovery loop
+
+```bash
+openclaw nodes status
+openclaw nodes describe --node <idOrNameOrIp>
+openclaw approvals get --node <idOrNameOrIp>
+openclaw logs --follow
+```
+
+If still stuck:
+
+- Re-approve device pairing.
+- Re-open node app (foreground).
+- Re-grant OS permissions.
+- Recreate/adjust exec approval policy.
+
+Related:
+
+- [/nodes/index](/nodes/index)
+- [/nodes/camera](/nodes/camera)
+- [/nodes/location-command](/nodes/location-command)
+- [/tools/exec-approvals](/tools/exec-approvals)
+- [/gateway/pairing](/gateway/pairing)

docs/perplexity.md

@@ -15,12 +15,12 @@ through Perplexity’s direct API or via OpenRouter.
 
 ### Perplexity (direct)
 
-- Base URL: https://api.perplexity.ai
+- Base URL: [https://api.perplexity.ai](https://api.perplexity.ai)
 - Environment variable: `PERPLEXITY_API_KEY`
 
 ### OpenRouter (alternative)
 
-- Base URL: https://openrouter.ai/api/v1
+- Base URL: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)
 - Environment variable: `OPENROUTER_API_KEY`
 - Supports prepaid/crypto credits.
 

docs/pi-dev.md

@@ -66,5 +66,5 @@ If you only want to reset sessions, delete `agents/<agentId>/sessions/` and `age
 
 ## References
 
-- https://docs.openclaw.ai/testing
-- https://docs.openclaw.ai/start/getting-started
+- [https://docs.openclaw.ai/testing](https://docs.openclaw.ai/testing)
+- [https://docs.openclaw.ai/start/getting-started](https://docs.openclaw.ai/start/getting-started)

docs/platforms/android.md

@@ -98,10 +98,13 @@ Pairing details: [Gateway pairing](/gateway/pairing).
 ### 5) Verify the node is connected
 
 - Via nodes status:
+
   ```bash
   openclaw nodes status
   ```
+
 - Via Gateway:
+
   ```bash
   openclaw gateway call node.list --params "{}"
   ```

docs/platforms/mac/dev-setup.md

@@ -13,8 +13,8 @@ This guide covers the necessary steps to build and run the OpenClaw macOS applic
 
 Before building the app, ensure you have the following installed:
 
-1.  **Xcode 26.2+**: Required for Swift development.
-2.  **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts.
+1. **Xcode 26.2+**: Required for Swift development.
+2. **Node.js 22+ & pnpm**: Required for the gateway, CLI, and packaging scripts.
 
 ## 1. Install Dependencies
 
@@ -35,7 +35,7 @@ To build the macOS app and package it into `dist/OpenClaw.app`, run:
 If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`).
 
 For dev run modes, signing flags, and Team ID troubleshooting, see the macOS app README:
-https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
+[https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md](https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md)
 
 > **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
 
@@ -45,9 +45,9 @@ The macOS app expects a global `openclaw` CLI install to manage background tasks
 
 **To install it (recommended):**
 
-1.  Open the OpenClaw app.
-2.  Go to the **General** settings tab.
-3.  Click **"Install CLI"**.
+1. Open the OpenClaw app.
+2. Go to the **General** settings tab.
+3. Click **"Install CLI"**.
 
 Alternatively, install it manually:
 
@@ -82,9 +82,11 @@ If the app crashes when you try to allow **Speech Recognition** or **Microphone*
 **Fix:**
 
 1. Reset the TCC permissions:
+
    ```bash
    tccutil reset All bot.molt.mac.debug
    ```
+
 2. If that fails, change the `BUNDLE_ID` temporarily in [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) to force a "clean slate" from macOS.
 
 ### Gateway "Starting..." indefinitely

docs/platforms/mac/permissions.md

@@ -40,5 +40,11 @@ sudo tccutil reset ScreenCapture bot.molt.mac
 sudo tccutil reset AppleEvents
 ```
 
+## Files and folders permissions (Desktop/Documents/Downloads)
+
+macOS may also gate Desktop, Documents, and Downloads for terminal/background processes. If file reads or directory listings hang, grant access to the same process context that performs file operations (for example Terminal/iTerm, LaunchAgent-launched app, or SSH process).
+
+Workaround: move files into the OpenClaw workspace (`~/.openclaw/workspace`) if you want to avoid per-folder grants.
+
 If you are testing permissions, always sign with a real certificate. Ad-hoc
 builds are only acceptable for quick local runs where permissions do not matter.

docs/platforms/mac/release.md

@@ -34,17 +34,17 @@ Notes:
 # From repo root; set release IDs so Sparkle feed is enabled.
 # APP_BUILD must be numeric + monotonic for Sparkle compare.
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.4 \
+APP_VERSION=2026.2.6 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-app.sh
 
 # Zip for distribution (includes resource forks for Sparkle delta support)
-ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.4.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.6.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.4.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.6.dmg
 
 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -52,14 +52,14 @@ scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.4.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
 BUNDLE_ID=bot.molt.mac \
-APP_VERSION=2026.2.4 \
+APP_VERSION=2026.2.6 \
 APP_BUILD="$(git rev-list --count HEAD)" \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
 
 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.4.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.6.dSYM.zip
 ```
 
 ## Appcast entry
@@ -67,7 +67,7 @@ ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenCl
 Use the release note generator so Sparkle renders formatted HTML notes:
 
 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.4.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.2.6.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
 ```
 
 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
@@ -75,7 +75,7 @@ Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when
 
 ## Publish & verify
 
-- Upload `OpenClaw-2026.2.4.zip` (and `OpenClaw-2026.2.4.dSYM.zip`) to the GitHub release for tag `v2026.2.4`.
+- Upload `OpenClaw-2026.2.6.zip` (and `OpenClaw-2026.2.6.dSYM.zip`) to the GitHub release for tag `v2026.2.6`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`.
 - Sanity checks:
   - `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` returns 200.

docs/platforms/mac/webchat.md

@@ -19,9 +19,11 @@ agent (with a session switcher for other sessions).
 
 - Manual: Lobster menu → “Open Chat”.
 - Auto‑open for testing:
+
   ```bash
   dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat
   ```
+
 - Logs: `./scripts/clawlog.sh` (subsystem `bot.molt`, category `WebChatSwiftUI`).
 
 ## How it’s wired

docs/platforms/windows.md

@@ -20,7 +20,7 @@ Native Windows companion apps are planned.
 
 - [Getting Started](/start/getting-started) (use inside WSL)
 - [Install & updates](/install/updating)
-- Official WSL2 guide (Microsoft): https://learn.microsoft.com/windows/wsl/install
+- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
 
 ## Gateway
 

docs/prose.md

@@ -11,7 +11,7 @@ title: "OpenProse"
 
 OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In OpenClaw it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow.
 
-Official site: https://www.prose.md
+Official site: [https://www.prose.md](https://www.prose.md)
 
 ## What it can do
 

docs/providers/claude-max-api-proxy.md

@@ -131,9 +131,9 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
 
 ## Links
 
-- **npm:** https://www.npmjs.com/package/claude-max-api-proxy
-- **GitHub:** https://github.com/atalovesyou/claude-max-api-proxy
-- **Issues:** https://github.com/atalovesyou/claude-max-api-proxy/issues
+- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
+- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
+- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
 
 ## Notes
 

docs/providers/deepgram.md

@@ -15,8 +15,8 @@ When enabled, OpenClaw uploads the audio file to Deepgram and injects the transc
 into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**;
 it uses the pre-recorded transcription endpoint.
 
-Website: https://deepgram.com  
-Docs: https://developers.deepgram.com
+Website: [https://deepgram.com](https://deepgram.com)  
+Docs: [https://developers.deepgram.com](https://developers.deepgram.com)
 
 ## Quick start
 

docs/providers/index.md

@@ -50,6 +50,7 @@ See [Venice AI](/providers/venice).
 - [MiniMax](/providers/minimax)
 - [Venice (Venice AI, privacy-focused)](/providers/venice)
 - [Ollama (local models)](/providers/ollama)
+- [Qianfan](/providers/qianfan)
 
 ## Transcription providers
 

docs/providers/minimax.md

@@ -179,7 +179,7 @@ Use the interactive config wizard to set MiniMax without editing JSON:
 - Model refs are `minimax/<model>`.
 - Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
 - Update pricing values in `models.json` if you need exact cost tracking.
-- Referral link for MiniMax Coding Plan (10% off): https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link
+- Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
 - See [/concepts/model-providers](/concepts/model-providers) for provider rules.
 - Use `openclaw models list` and `openclaw models set minimax/MiniMax-M2.1` to switch.
 

docs/providers/models.md

@@ -46,6 +46,7 @@ See [Venice AI](/providers/venice).
 - [MiniMax](/providers/minimax)
 - [Venice (Venice AI)](/providers/venice)
 - [Amazon Bedrock](/bedrock)
+- [Qianfan](/providers/qianfan)
 
 For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
 see [Model providers](/concepts/model-providers).

docs/providers/moonshot.md

@@ -15,14 +15,14 @@ Kimi Coding with `kimi-coding/k2p5`.
 
 Current Kimi K2 model IDs:
 
-{/_ moonshot-kimi-k2-ids:start _/ && null}
+{/_moonshot-kimi-k2-ids:start_/ && null}
 
 - `kimi-k2.5`
 - `kimi-k2-0905-preview`
 - `kimi-k2-turbo-preview`
 - `kimi-k2-thinking`
 - `kimi-k2-thinking-turbo`
-  {/_ moonshot-kimi-k2-ids:end _/ && null}
+  {/_moonshot-kimi-k2-ids:end_/ && null}
 
 ```bash
 openclaw onboard --auth-choice moonshot-api-key

docs/providers/ollama.md

@@ -12,7 +12,7 @@ Ollama is a local LLM runtime that makes it easy to run open-source models on yo
 
 ## Quick start
 
-1. Install Ollama: https://ollama.ai
+1. Install Ollama: [https://ollama.ai](https://ollama.ai)
 
 2. Pull a model:
 

docs/providers/qianfan.md

@@ -0,0 +1,38 @@
+---
+summary: "Use Qianfan's unified API to access many models in OpenClaw"
+read_when:
+  - You want a single API key for many LLMs
+  - You need Baidu Qianfan setup guidance
+title: "Qianfan"
+---
+
+# Qianfan Provider Guide
+
+Qianfan is Baidu's MaaS platform, provides a **unified API** that routes requests to many models behind a single
+endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
+
+## Prerequisites
+
+1. A Baidu Cloud account with Qianfan API access
+2. An API key from the Qianfan console
+3. OpenClaw installed on your system
+
+## Getting Your API Key
+
+1. Visit the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey)
+2. Create a new application or select an existing one
+3. Generate an API key (format: `bce-v3/ALTAK-...`)
+4. Copy the API key for use with OpenClaw
+
+## CLI setup
+
+```bash
+openclaw onboard --auth-choice qianfan-api-key
+```
+
+## Related Documentation
+
+- [OpenClaw Configuration](/configuration)
+- [Model Providers](/concepts/model-providers)
+- [Agent Setup](/agents)
+- [Qianfan API Documentation](https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb)

docs/reference/AGENTS.default.md

@@ -110,7 +110,6 @@ git commit -m "Add Clawd workspace"
 - **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
 - **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
 - **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
-- **bird** — X/Twitter CLI to tweet, reply, read threads, and search without a browser.
 - **agent-tools** — Utility toolkit for automations and helper scripts.
 
 ## Usage Notes

docs/reference/api-usage-costs.md

@@ -66,7 +66,8 @@ Semantic memory search uses **embedding APIs** when configured for remote provid
 
 - `memorySearch.provider = "openai"` → OpenAI embeddings
 - `memorySearch.provider = "gemini"` → Gemini embeddings
-- Optional fallback to OpenAI if local embeddings fail
+- `memorySearch.provider = "voyage"` → Voyage embeddings
+- Optional fallback to a remote provider if local embeddings fail
 
 You can keep it local with `memorySearch.provider = "local"` (no API usage).
 

docs/reference/credits.md

@@ -17,8 +17,8 @@ OpenClaw = CLAW + TARDIS, because every space lobster needs a time and space mac
 
 ## Core contributors
 
-- **Maxim Vovshin** (@Hyaxia, 36747317+Hyaxia@users.noreply.github.com) - Blogwatcher skill
-- **Nacho Iacovino** (@nachoiacovino, nacho.iacovino@gmail.com) - Location parsing (Telegram and WhatsApp)
+- **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com)) - Blogwatcher skill
+- **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com)) - Location parsing (Telegram and WhatsApp)
 
 ## License
 

docs/reference/pipeline.md

@@ -0,0 +1,131 @@
+# Release Pipeline
+
+This document describes openclaw's staged release pipeline for contributors and maintainers.
+
+## Branch Strategy
+
+```
+dev/* ──────► develop ──────► alpha ──────► beta ──────► main
+feature/*         │              │            │            │
+fix/*             │              │            │            │
+                  ▼              ▼            ▼            ▼
+              Internal       Alpha         Beta        Stable
+              testing      testers       testers      release
+```
+
+### Branch Purposes
+
+| Branch                        | Purpose             | npm tag   | Who uses it      |
+| ----------------------------- | ------------------- | --------- | ---------------- |
+| `dev/*`, `feature/*`, `fix/*` | Active development  | -         | Contributors     |
+| `develop`                     | Integration branch  | -         | CI validation    |
+| `alpha`                       | Early testing       | `@alpha`  | Internal testers |
+| `beta`                        | Pre-release testing | `@beta`   | Beta testers     |
+| `main`                        | Production releases | `@latest` | Everyone         |
+
+## Workflow Overview
+
+### 1. Feature Development
+
+1. Create a branch: `git checkout -b dev/my-feature`
+2. Make changes and push
+3. **Auto-PR created** to `develop` via `feature-pr.yml`
+4. Get review, iterate, merge to `develop`
+
+### 2. Promotion Through Stages
+
+When code lands in `develop`, the `promote-branch.yml` workflow:
+
+1. Runs tests appropriate for that stage
+2. Creates a PR to the next branch (develop → alpha → beta → main)
+3. Auto-merges `develop → alpha` if tests pass
+4. Requires manual approval for `alpha → beta` and `beta → main`
+
+### 3. Releases
+
+Releases are triggered manually via the **Release** workflow:
+
+1. Go to Actions → Release → Run workflow
+2. Select release type: `alpha`, `beta`, or `stable`
+3. Workflow runs: version bump → changelog → tests → npm publish → Docker push
+
+## Test Coverage by Stage
+
+| Stage   | Tests Run                                             |
+| ------- | ----------------------------------------------------- |
+| develop | tsgo, lint, format, protocol, unit tests (Node + Bun) |
+| alpha   | + secrets scan                                        |
+| beta    | + Windows tests                                       |
+| stable  | + macOS tests, install smoke tests                    |
+
+## Emergency Hotfixes
+
+For critical production issues:
+
+1. Create branch: `git checkout -b hotfix/critical-bug`
+2. Push → **Auto-PR created** directly to `main`
+3. Get expedited review (skip staging)
+4. After merge, cherry-pick to `develop`, `alpha`, `beta` to sync
+
+```bash
+# After hotfix merges to main
+git checkout develop && git cherry-pick <commit-sha> && git push
+git checkout alpha && git cherry-pick <commit-sha> && git push
+git checkout beta && git cherry-pick <commit-sha> && git push
+```
+
+## npm Installation by Channel
+
+```bash
+# Stable (default)
+npm install -g openclaw
+
+# Beta testing
+npm install -g openclaw@beta
+
+# Alpha testing (bleeding edge)
+npm install -g openclaw@alpha
+```
+
+## Docker Images
+
+Images are published to GitHub Container Registry:
+
+```bash
+# Stable
+docker pull ghcr.io/openclaw/openclaw:latest
+
+# Beta
+docker pull ghcr.io/openclaw/openclaw:beta
+
+# Specific version
+docker pull ghcr.io/openclaw/openclaw:2026.2.6
+```
+
+## Version Format
+
+- **Stable**: `YYYY.M.D` (e.g., `2026.2.6`)
+- **Beta**: `YYYY.M.D-beta.N` (e.g., `2026.2.6-beta.1`)
+- **Alpha**: `YYYY.M.D-alpha.N` (e.g., `2026.2.6-alpha.3`)
+
+## Setup
+
+### Required Secrets
+
+Configure these in GitHub repo Settings → Secrets and variables → Actions:
+
+| Secret                | Required?            | Purpose                                                 | How to get it                                               |
+| --------------------- | -------------------- | ------------------------------------------------------- | ----------------------------------------------------------- |
+| `GITHUB_TOKEN`        | Automatic            | PR creation, Docker registry, branch ops                | Provided by GitHub Actions — no setup needed                |
+| `NPM_TOKEN`           | Yes (for publishing) | npm publish with `@alpha`, `@beta`, `@latest` tags      | npmjs.com → Access Tokens → Generate New Token → Automation |
+| `DISCORD_WEBHOOK_URL` | Optional             | Notifications for promotions, test results, deployments | Discord → Server Settings → Integrations → Webhooks         |
+
+Without `NPM_TOKEN`, the pipeline runs normally but skips npm publishing. Without `DISCORD_WEBHOOK_URL`, notifications are silently skipped.
+
+### Branch Setup
+
+Staging branches are auto-created from `main` when the first promotion runs. No manual setup required.
+
+### Rollback
+
+The rollback workflow (`Actions → Rollback`) re-tags npm and Docker to a previous version. Requires `NPM_TOKEN` and is manual-trigger only.