fix: enforce feishu dm policy + pairing flow (#14876) (thanks @coygeek)

Generated by staged fix workflow.

.agents/archive/PR_WORKFLOW_V1.md

@@ -0,0 +1,181 @@
+# PR Workflow for Maintainers
+
+Please read this in full and do not skip sections.
+This is the single source of truth for the maintainer PR workflow.
+
+## Triage order
+
+Process PRs **oldest to newest**. Older PRs are more likely to have merge conflicts and stale dependencies; resolving them first keeps the queue healthy and avoids snowballing rebase pain.
+
+## Working rule
+
+Skills execute workflow. Maintainers provide judgment.
+Always pause between skills to evaluate technical direction, not just command success.
+
+These three skills must be used in order:
+
+1. `review-pr` — review only, produce findings
+2. `prepare-pr` — rebase, fix, gate, push to PR head branch
+3. `merge-pr` — squash-merge, verify MERGED state, clean up
+
+They are necessary, but not sufficient. Maintainers must steer between steps and understand the code before moving forward.
+
+Treat PRs as reports first, code second.
+If submitted code is low quality, ignore it and implement the best solution for the problem.
+
+Do not continue if you cannot verify the problem is real or test the fix.
+
+## Coding Agent
+
+Use ChatGPT 5.3 Codex High. Fall back to 5.2 Codex High or 5.3 Codex Medium if necessary.
+
+## PR quality bar
+
+- Do not trust PR code by default.
+- Do not merge changes you cannot validate with a reproducible problem and a tested fix.
+- Keep types strict. Do not use `any` in implementation code.
+- Keep external-input boundaries typed and validated, including CLI input, environment variables, network payloads, and tool output.
+- Keep implementations properly scoped. Fix root causes, not local symptoms.
+- Identify and reuse canonical sources of truth so behavior does not drift across the codebase.
+- Harden changes. Always evaluate security impact and abuse paths.
+- Understand the system before changing it. Never make the codebase messier just to clear a PR queue.
+
+## Rebase and conflict resolution
+
+Before any substantive review or prep work, **always rebase the PR branch onto current `main` and resolve merge conflicts first**. A PR that cannot cleanly rebase is not ready for review — fix conflicts before evaluating correctness.
+
+- During `prepare-pr`: rebase onto `main` as the first step, before fixing findings or running gates.
+- If conflicts are complex or touch areas you do not understand, stop and escalate.
+- Prefer **rebase** for linear history; **squash** when commit history is messy or unhelpful.
+
+## Commit and changelog rules
+
+- Create commits with `scripts/committer "<msg>" <file...>`; avoid manual `git add`/`git commit` so staging stays scoped.
+- Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
+- During `prepare-pr`, use this commit subject format: `fix: <summary> (openclaw#<PR>) thanks @<pr-author>`.
+- Group related changes; avoid bundling unrelated refactors.
+- Changelog workflow: keep the latest released version at the top (no `Unreleased`); after publishing, bump the version and start a new top section.
+- When working on a PR: add a changelog entry with the PR number and thank the contributor.
+- When working on an issue: reference the issue in the changelog entry.
+- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.
+
+## Co-contributor and clawtributors
+
+- If we squash, add the PR author as a co-contributor in the commit body using a `Co-authored-by:` trailer.
+- When maintainer prepares and merges the PR, add the maintainer as an additional `Co-authored-by:` trailer too.
+- Avoid `--auto` merges for maintainer landings. Merge only after checks are green so the maintainer account is the actor and attribution is deterministic.
+- For squash merges, set `--author-email` to a reviewer-owned email with fallback candidates; if merge fails due to author-email validation, retry once with the next candidate.
+- If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor.
+- When merging a PR: leave a PR comment that explains exactly what we did, include the SHA hashes, and record the comment URL in the final report.
+- When merging a PR from a new contributor: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README.
+
+## Review mode vs landing mode
+
+- **Review mode (PR link only):** read `gh pr view`/`gh pr diff`; **do not** switch branches; **do not** change code.
+- **Landing mode (exception path):** use only when normal `review-pr -> prepare-pr -> merge-pr` flow cannot safely preserve attribution or cannot satisfy branch protection. Create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: the contributor needs to be in the git graph after this!
+
+## Pre-review safety checks
+
+- Before starting a review when a GH Issue/PR is pasted: use an isolated `.worktrees/pr-<PR>` checkout from `origin/main`. Do not require a clean main checkout, and do not run `git pull` in a dirty main checkout.
+- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed.
+- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
+- Read `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) for what we expect from contributors.
+
+## Unified workflow
+
+Entry criteria:
+
+- PR URL/number is known.
+- Problem statement is clear enough to attempt reproduction.
+- A realistic verification path exists (tests, integration checks, or explicit manual validation).
+
+### 1) `review-pr`
+
+Purpose:
+
+- Review only: correctness, value, security risk, tests, docs, and changelog impact.
+- Produce structured findings and a recommendation.
+
+Expected output:
+
+- Recommendation: ready, needs work, needs discussion, or close.
+- `.local/review.md` with actionable findings.
+
+Maintainer checkpoint before `prepare-pr`:
+
+```
+What problem are they trying to solve?
+What is the most optimal implementation?
+Can we fix up everything?
+Do we have any questions?
+```
+
+Stop and escalate instead of continuing if:
+
+- The problem cannot be reproduced or confirmed.
+- The proposed PR scope does not match the stated problem.
+- The design introduces unresolved security or trust-boundary concerns.
+
+### 2) `prepare-pr`
+
+Purpose:
+
+- Make the PR merge-ready on its head branch.
+- Rebase onto current `main` first, then fix blocker/important findings, then run gates.
+- In fresh worktrees, bootstrap dependencies before local gates (`pnpm install --frozen-lockfile`).
+
+Expected output:
+
+- Updated code and tests on the PR head branch.
+- `.local/prep.md` with changes, verification, and current HEAD SHA.
+- Final status: `PR is ready for /mergepr`.
+
+Maintainer checkpoint before `merge-pr`:
+
+```
+Is this the most optimal implementation?
+Is the code properly scoped?
+Is the code properly reusing existing logic in the codebase?
+Is the code properly typed?
+Is the code hardened?
+Do we have enough tests?
+Do we need regression tests?
+Are tests using fake timers where appropriate? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops)
+Do not add performative tests, ensure tests are real and there are no regressions.
+Do you see any follow-up refactors we should do?
+Take your time, fix it properly, refactor if necessary.
+Did any changes introduce any potential security vulnerabilities?
+```
+
+Stop and escalate instead of continuing if:
+
+- You cannot verify behavior changes with meaningful tests or validation.
+- Fixing findings requires broad architecture changes outside safe PR scope.
+- Security hardening requirements remain unresolved.
+
+### 3) `merge-pr`
+
+Purpose:
+
+- Merge only after review and prep artifacts are present and checks are green.
+- Use deterministic squash merge flow (`--match-head-commit` + explicit subject/body with co-author trailer), then verify the PR ends in `MERGED` state.
+- If no required checks are configured on the PR, treat that as acceptable and continue after branch-up-to-date validation.
+
+Go or no-go checklist before merge:
+
+- All BLOCKER and IMPORTANT findings are resolved.
+- Verification is meaningful and regression risk is acceptably low.
+- Docs and changelog are updated when required.
+- Required CI checks are green and the branch is not behind `main`.
+
+Expected output:
+
+- Successful merge commit and recorded merge SHA.
+- Worktree cleanup after successful merge.
+- Comment on PR indicating merge was successful.
+
+Maintainer checkpoint after merge:
+
+- Were any refactors intentionally deferred and now need follow-up issue(s)?
+- Did this reveal broader architecture or test gaps we should address?
+- Run `bun scripts/update-clawtributors.ts` if the contributor is new.

.agents/archive/merge-pr-v1/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: merge-pr
+description: Merge a GitHub PR via squash after /prepare-pr. Use when asked to merge a ready PR. Do not push to main or modify code. Ensure the PR ends in MERGED state and clean up worktrees after success.
+---
+
+# Merge PR
+
+## Overview
+
+Merge a prepared PR via deterministic squash merge (`--match-head-commit` + explicit co-author trailer), then clean up the worktree after success.
+
+## Inputs
+
+- Ask for PR number or URL.
+- If missing, use `.local/prep.env` from the worktree if present.
+- If ambiguous, ask.
+
+## Safety
+
+- Use `gh pr merge --squash` as the only path to `main`.
+- Do not run `git push` at all during merge.
+- Do not use `gh pr merge --auto` for maintainer landings.
+- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
+
+## Execution Rule
+
+- Execute the workflow. Do not stop after printing the TODO checklist.
+- If delegating, require the delegate to run commands and capture outputs.
+
+## Known Footguns
+
+- If you see "fatal: not a git repository", you are in the wrong directory. Move to the repo root and retry.
+- Read `.local/review.md`, `.local/prep.md`, and `.local/prep.env` in the worktree. Do not skip.
+- Always merge with `--match-head-commit "$PREP_HEAD_SHA"` to prevent racing stale or changed heads.
+- Clean up `.worktrees/pr-<PR>` only after confirmed `MERGED`.
+
+## Completion Criteria
+
+- Ensure `gh pr merge` succeeds.
+- Ensure PR state is `MERGED`, never `CLOSED`.
+- Record the merge SHA.
+- Leave a PR comment with merge SHA and prepared head SHA, and capture the comment URL.
+- Run cleanup only after merge success.
+
+## First: Create a TODO Checklist
+
+Create a checklist of all merge steps, print it, then continue and execute the commands.
+
+## Setup: Use a Worktree
+
+Use an isolated worktree for all merge work.
+
+```sh
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+gh auth status
+
+WORKTREE_DIR=".worktrees/pr-<PR>"
+cd "$WORKTREE_DIR"
+```
+
+Run all commands inside the worktree directory.
+
+## Load Local Artifacts (Mandatory)
+
+Expect these files from earlier steps:
+
+- `.local/review.md` from `/review-pr`
+- `.local/prep.md` from `/prepare-pr`
+- `.local/prep.env` from `/prepare-pr`
+
+```sh
+ls -la .local || true
+
+for required in .local/review.md .local/prep.md .local/prep.env; do
+  if [ ! -f "$required" ]; then
+    echo "Missing $required. Stop and run /review-pr then /prepare-pr."
+    exit 1
+  fi
+done
+
+sed -n '1,120p' .local/review.md
+sed -n '1,120p' .local/prep.md
+source .local/prep.env
+```
+
+## Steps
+
+1. Identify PR meta and verify prepared SHA still matches
+
+```sh
+pr_meta_json=$(gh pr view <PR> --json number,title,state,isDraft,author,headRefName,headRefOid,baseRefName,headRepository,body)
+printf '%s\n' "$pr_meta_json" | jq '{number,title,state,isDraft,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}'
+pr_title=$(printf '%s\n' "$pr_meta_json" | jq -r .title)
+pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number)
+pr_head_sha=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid)
+contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login)
+is_draft=$(printf '%s\n' "$pr_meta_json" | jq -r .isDraft)
+
+if [ "$is_draft" = "true" ]; then
+  echo "ERROR: PR is draft. Stop and run /prepare-pr after draft is cleared."
+  exit 1
+fi
+
+if [ "$pr_head_sha" != "$PREP_HEAD_SHA" ]; then
+  echo "ERROR: PR head changed after /prepare-pr (expected $PREP_HEAD_SHA, got $pr_head_sha). Re-run /prepare-pr."
+  exit 1
+fi
+```
+
+2. Run sanity checks
+
+Stop if any are true:
+
+- PR is a draft.
+- Required checks are failing.
+- Branch is behind main.
+
+If checks are pending, wait for completion before merging. Do not use `--auto`.
+If no required checks are configured, continue.
+
+```sh
+gh pr checks <PR> --required --watch --fail-fast || true
+checks_json=$(gh pr checks <PR> --required --json name,bucket,state 2>/tmp/gh-checks.err || true)
+if [ -z "$checks_json" ]; then
+  checks_json='[]'
+fi
+required_count=$(printf '%s\n' "$checks_json" | jq 'length')
+if [ "$required_count" -eq 0 ]; then
+  echo "No required checks configured for this PR."
+fi
+printf '%s\n' "$checks_json" | jq -r '.[] | "\(.bucket)\t\(.name)\t\(.state)"'
+
+failed_required=$(printf '%s\n' "$checks_json" | jq '[.[] | select(.bucket=="fail")] | length')
+pending_required=$(printf '%s\n' "$checks_json" | jq '[.[] | select(.bucket=="pending")] | length')
+if [ "$failed_required" -gt 0 ]; then
+  echo "Required checks are failing, run /prepare-pr."
+  exit 1
+fi
+if [ "$pending_required" -gt 0 ]; then
+  echo "Required checks are still pending, retry /merge-pr when green."
+  exit 1
+fi
+
+git fetch origin main
+git fetch origin pull/<PR>/head:pr-<PR> --force
+git merge-base --is-ancestor origin/main pr-<PR> || (echo "PR branch is behind main, run /prepare-pr" && exit 1)
+```
+
+If anything is failing or behind, stop and say to run `/prepare-pr`.
+
+3. Merge PR with explicit attribution metadata
+
+```sh
+reviewer=$(gh api user --jq .login)
+reviewer_id=$(gh api user --jq .id)
+coauthor_email=${COAUTHOR_EMAIL:-"$contrib@users.noreply.github.com"}
+if [ -z "$coauthor_email" ] || [ "$coauthor_email" = "null" ]; then
+  contrib_id=$(gh api users/$contrib --jq .id)
+  coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com"
+fi
+
+gh_email=$(gh api user --jq '.email // ""' || true)
+git_email=$(git config user.email || true)
+mapfile -t reviewer_email_candidates < <(
+  printf '%s\n' \
+    "$gh_email" \
+    "$git_email" \
+    "${reviewer_id}+${reviewer}@users.noreply.github.com" \
+    "${reviewer}@users.noreply.github.com" | awk 'NF && !seen[$0]++'
+)
+[ "${#reviewer_email_candidates[@]}" -gt 0 ] || { echo "ERROR: could not resolve reviewer author email"; exit 1; }
+reviewer_email="${reviewer_email_candidates[0]}"
+
+cat > .local/merge-body.txt <<EOF
+Merged via /review-pr -> /prepare-pr -> /merge-pr.
+
+Prepared head SHA: $PREP_HEAD_SHA
+Co-authored-by: $contrib <$coauthor_email>
+Co-authored-by: $reviewer <$reviewer_email>
+Reviewed-by: @$reviewer
+EOF
+
+run_merge() {
+  local email="$1"
+  local stderr_file
+  stderr_file=$(mktemp)
+  if gh pr merge <PR> \
+    --squash \
+    --delete-branch \
+    --match-head-commit "$PREP_HEAD_SHA" \
+    --author-email "$email" \
+    --subject "$pr_title (#$pr_number)" \
+    --body-file .local/merge-body.txt \
+    2> >(tee "$stderr_file" >&2)
+  then
+    rm -f "$stderr_file"
+    return 0
+  fi
+  merge_err=$(cat "$stderr_file")
+  rm -f "$stderr_file"
+  return 1
+}
+
+merge_err=""
+selected_merge_author_email="$reviewer_email"
+if ! run_merge "$selected_merge_author_email"; then
+  if printf '%s\n' "$merge_err" | rg -qi 'author.?email|email.*associated|associated.*email|invalid.*email' && [ "${#reviewer_email_candidates[@]}" -ge 2 ]; then
+    selected_merge_author_email="${reviewer_email_candidates[1]}"
+    echo "Retrying once with fallback author email: $selected_merge_author_email"
+    run_merge "$selected_merge_author_email" || { echo "ERROR: merge failed after fallback retry"; exit 1; }
+  else
+    echo "ERROR: merge failed"
+    exit 1
+  fi
+fi
+```
+
+Retry is allowed exactly once when the error is clearly author-email validation.
+
+4. Verify PR state and capture merge SHA
+
+```sh
+state=$(gh pr view <PR> --json state --jq .state)
+if [ "$state" != "MERGED" ]; then
+  echo "Merge not finalized yet (state=$state), waiting up to 15 minutes..."
+  for _ in $(seq 1 90); do
+    sleep 10
+    state=$(gh pr view <PR> --json state --jq .state)
+    if [ "$state" = "MERGED" ]; then
+      break
+    fi
+  done
+fi
+
+if [ "$state" != "MERGED" ]; then
+  echo "ERROR: PR state is $state after waiting. Leave worktree and retry /merge-pr later."
+  exit 1
+fi
+
+merge_sha=$(gh pr view <PR> --json mergeCommit --jq '.mergeCommit.oid')
+if [ -z "$merge_sha" ] || [ "$merge_sha" = "null" ]; then
+  echo "ERROR: merge commit SHA missing."
+  exit 1
+fi
+
+commit_body=$(gh api repos/:owner/:repo/commits/$merge_sha --jq .commit.message)
+contrib=${contrib:-$(gh pr view <PR> --json author --jq .author.login)}
+reviewer=${reviewer:-$(gh api user --jq .login)}
+printf '%s\n' "$commit_body" | rg -q "^Co-authored-by: $contrib <" || { echo "ERROR: missing PR author co-author trailer"; exit 1; }
+printf '%s\n' "$commit_body" | rg -q "^Co-authored-by: $reviewer <" || { echo "ERROR: missing reviewer co-author trailer"; exit 1; }
+
+echo "merge_sha=$merge_sha"
+```
+
+5. PR comment
+
+Use a multiline heredoc with interpolation enabled.
+
+```sh
+ok=0
+comment_output=""
+for _ in 1 2 3; do
+  if comment_output=$(gh pr comment <PR> -F - <<EOF
+Merged via squash.
+
+- Prepared head SHA: $PREP_HEAD_SHA
+- Merge commit: $merge_sha
+
+Thanks @$contrib!
+EOF
+); then
+    ok=1
+    break
+  fi
+  sleep 2
+done
+
+[ "$ok" -eq 1 ] || { echo "ERROR: failed to post PR comment after retries"; exit 1; }
+comment_url=$(printf '%s\n' "$comment_output" | rg -o 'https://github.com/[^ ]+/pull/[0-9]+#issuecomment-[0-9]+' -m1 || true)
+[ -n "$comment_url" ] || comment_url="unresolved"
+echo "comment_url=$comment_url"
+```
+
+6. Clean up worktree only on success
+
+Run cleanup only if step 4 returned `MERGED`.
+
+```sh
+cd "$repo_root"
+git worktree remove ".worktrees/pr-<PR>" --force
+git branch -D temp/pr-<PR> 2>/dev/null || true
+git branch -D pr-<PR> 2>/dev/null || true
+git branch -D pr-<PR>-prep 2>/dev/null || true
+```
+
+## Guardrails
+
+- Worktree only.
+- Do not close PRs.
+- End in MERGED state.
+- Clean up only after merge success.
+- Never push to main. Use `gh pr merge --squash` only.
+- Do not run `git push` at all in this command.

.agents/archive/merge-pr-v1/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Merge PR"
+  short_description: "Merge GitHub PRs via squash"
+  default_prompt: "Use $merge-pr to merge a GitHub PR via squash after preparation."

.agents/archive/prepare-pr-v1/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: prepare-pr
+description: Prepare a GitHub PR for merge by rebasing onto main, fixing review findings, running gates, committing fixes, and pushing to the PR head branch. Use after /review-pr. Never merge or push to main.
+---
+
+# Prepare PR
+
+## Overview
+
+Prepare a PR head branch for merge with review fixes, green gates, and deterministic merge handoff artifacts.
+
+## Inputs
+
+- Ask for PR number or URL.
+- If missing, use `.local/pr-meta.env` from the PR worktree if present.
+- If ambiguous, ask.
+
+## Safety
+
+- Never push to `main` or `origin/main`. Push only to the PR head branch.
+- Never run `git push` without explicit remote and branch. Do not run bare `git push`.
+- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
+- Do not run `git clean -fdx`.
+- Do not run `git add -A` or `git add .`.
+
+## Execution Rule
+
+- Execute the workflow. Do not stop after printing the TODO checklist.
+- If delegating, require the delegate to run commands and capture outputs.
+
+## Completion Criteria
+
+- Rebase PR commits onto `origin/main`.
+- Fix all BLOCKER and IMPORTANT items from `.local/review.md`.
+- Commit prep changes with required subject format.
+- Run required gates and pass (`pnpm test` may be skipped only for high-confidence docs-only changes).
+- Push the updated HEAD back to the PR head branch.
+- Write `.local/prep.md` and `.local/prep.env`.
+- Output exactly: `PR is ready for /mergepr`.
+
+## First: Create a TODO Checklist
+
+Create a checklist of all prep steps, print it, then continue and execute the commands.
+
+## Setup: Use a Worktree
+
+Use an isolated worktree for all prep work.
+
+```sh
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+gh auth status
+
+WORKTREE_DIR=".worktrees/pr-<PR>"
+if [ ! -d "$WORKTREE_DIR" ]; then
+  git fetch origin main
+  git worktree add "$WORKTREE_DIR" -b temp/pr-<PR> origin/main
+fi
+cd "$WORKTREE_DIR"
+mkdir -p .local
+```
+
+Run all commands inside the worktree directory.
+
+## Load Review Artifacts (Mandatory)
+
+```sh
+if [ ! -f .local/review.md ]; then
+  echo "Missing .local/review.md. Run /review-pr first and save findings."
+  exit 1
+fi
+
+if [ ! -f .local/pr-meta.env ]; then
+  echo "Missing .local/pr-meta.env. Run /review-pr first and save metadata."
+  exit 1
+fi
+
+sed -n '1,220p' .local/review.md
+source .local/pr-meta.env
+```
+
+## Steps
+
+1. Identify PR meta with one API call
+
+```sh
+pr_meta_json=$(gh pr view <PR> --json number,title,author,headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner,body)
+printf '%s\n' "$pr_meta_json" | jq '{number,title,author:.author.login,head:.headRefName,headSha:.headRefOid,base:.baseRefName,headRepo:.headRepository.nameWithOwner,headRepoOwner:.headRepositoryOwner.login,headRepoName:.headRepository.name,body}'
+
+pr_number=$(printf '%s\n' "$pr_meta_json" | jq -r .number)
+contrib=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login)
+head=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefName)
+pr_head_sha_before=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid)
+head_owner=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepositoryOwner.login // empty')
+head_repo_name=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.name // empty')
+head_repo_url=$(printf '%s\n' "$pr_meta_json" | jq -r '.headRepository.url // empty')
+
+if [ -n "${PR_HEAD:-}" ] && [ "$head" != "$PR_HEAD" ]; then
+  echo "ERROR: PR head branch changed from $PR_HEAD to $head. Re-run /review-pr."
+  exit 1
+fi
+```
+
+2. Fetch PR head and rebase on latest `origin/main`
+
+```sh
+git fetch origin pull/<PR>/head:pr-<PR> --force
+git checkout -B pr-<PR>-prep pr-<PR>
+git fetch origin main
+git rebase origin/main
+```
+
+If conflicts happen:
+
+- Resolve each conflicted file.
+- Run `git add <resolved_file>` for each file.
+- Run `git rebase --continue`.
+
+If the rebase gets confusing or you resolve conflicts 3 or more times, stop and report.
+
+3. Fix issues from `.local/review.md`
+
+- Fix all BLOCKER and IMPORTANT items.
+- NITs are optional.
+- Keep scope tight.
+
+Keep a running log in `.local/prep.md`:
+
+- List which review items you fixed.
+- List which files you touched.
+- Note behavior changes.
+
+4. Optional quick feedback tests before full gates
+
+Targeted tests are optional quick feedback, not a substitute for full gates.
+
+If running targeted tests in a fresh worktree:
+
+```sh
+if [ ! -x node_modules/.bin/vitest ]; then
+  pnpm install --frozen-lockfile
+fi
+```
+
+5. Commit prep fixes with required subject format
+
+Use `scripts/committer` with explicit file paths.
+
+Required subject format:
+
+- `fix: <summary> (openclaw#<PR>) thanks @<author>`
+
+```sh
+commit_msg="fix: <summary> (openclaw#$pr_number) thanks @$contrib"
+scripts/committer "$commit_msg" <changed file 1> <changed file 2> ...
+```
+
+If there are no local changes, do not create a no-op commit.
+
+Post-commit validation (mandatory):
+
+```sh
+subject=$(git log -1 --pretty=%s)
+echo "$subject" | rg -q "openclaw#$pr_number" || { echo "ERROR: commit subject missing openclaw#$pr_number"; exit 1; }
+echo "$subject" | rg -q "thanks @$contrib" || { echo "ERROR: commit subject missing thanks @$contrib"; exit 1; }
+```
+
+6. Decide verification mode and run required gates before pushing
+
+If you are highly confident the change is docs-only, you may skip `pnpm test`.
+
+High-confidence docs-only criteria (all must be true):
+
+- Every changed file is documentation-only (`docs/**`, `README*.md`, `CHANGELOG.md`, `*.md`, `*.mdx`, `mintlify.json`, `docs.json`).
+- No code, runtime, test, dependency, or build config files changed (`src/**`, `extensions/**`, `apps/**`, `package.json`, lockfiles, TS/JS config, test files, scripts).
+- `.local/review.md` does not call for non-doc behavior fixes.
+
+Suggested check:
+
+```sh
+changed_files=$(git diff --name-only origin/main...HEAD)
+non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true)
+
+docs_only=false
+if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then
+  docs_only=true
+fi
+
+echo "docs_only=$docs_only"
+```
+
+Bootstrap dependencies in a fresh worktree before gates:
+
+```sh
+if [ ! -d node_modules ]; then
+  pnpm install --frozen-lockfile
+fi
+```
+
+Run required gates:
+
+```sh
+pnpm build
+pnpm check
+
+if [ "$docs_only" = "true" ]; then
+  echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md
+else
+  pnpm test
+fi
+```
+
+Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix-and-rerun cycles.
+
+7. Push safely to the PR head branch
+
+Build `prhead` from owner/name first, then validate remote branch SHA before push.
+
+```sh
+if [ -n "$head_owner" ] && [ -n "$head_repo_name" ]; then
+  head_repo_push_url="https://github.com/$head_owner/$head_repo_name.git"
+elif [ -n "$head_repo_url" ] && [ "$head_repo_url" != "null" ]; then
+  case "$head_repo_url" in
+    *.git) head_repo_push_url="$head_repo_url" ;;
+    *) head_repo_push_url="$head_repo_url.git" ;;
+  esac
+else
+  echo "ERROR: unable to determine PR head repo push URL"
+  exit 1
+fi
+
+git remote add prhead "$head_repo_push_url" 2>/dev/null || git remote set-url prhead "$head_repo_push_url"
+
+echo "Pushing to branch: $head"
+if [ "$head" = "main" ] || [ "$head" = "master" ]; then
+  echo "ERROR: head branch is main/master. This is wrong. Stopping."
+  exit 1
+fi
+
+remote_sha=$(git ls-remote prhead "refs/heads/$head" | awk '{print $1}')
+if [ -z "$remote_sha" ]; then
+  echo "ERROR: remote branch refs/heads/$head not found on prhead"
+  exit 1
+fi
+if [ "$remote_sha" != "$pr_head_sha_before" ]; then
+  echo "ERROR: expected remote SHA $pr_head_sha_before, got $remote_sha. Re-fetch metadata and rebase first."
+  exit 1
+fi
+
+git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head || push_failed=1
+```
+
+If lease push fails because head moved, perform one automatic retry:
+
+```sh
+if [ "${push_failed:-0}" = "1" ]; then
+  echo "Lease push failed, retrying once with fresh PR head..."
+
+  pr_head_sha_before=$(gh pr view <PR> --json headRefOid --jq .headRefOid)
+  git fetch origin pull/<PR>/head:pr-<PR>-latest --force
+  git rebase pr-<PR>-latest
+
+  pnpm build
+  pnpm check
+  if [ "$docs_only" != "true" ]; then
+    pnpm test
+  fi
+
+  git push --force-with-lease=refs/heads/$head:$pr_head_sha_before prhead HEAD:$head
+fi
+```
+
+8. Verify PR head and base relation (Mandatory)
+
+```sh
+prep_head_sha=$(git rev-parse HEAD)
+pr_head_sha_after=$(gh pr view <PR> --json headRefOid --jq .headRefOid)
+
+if [ "$prep_head_sha" != "$pr_head_sha_after" ]; then
+  echo "ERROR: pushed head SHA does not match PR head SHA."
+  exit 1
+fi
+
+git fetch origin main
+git fetch origin pull/<PR>/head:pr-<PR>-verify --force
+git merge-base --is-ancestor origin/main pr-<PR>-verify && echo "PR is up to date with main" || (echo "ERROR: PR is still behind main, rebase again" && exit 1)
+git branch -D pr-<PR>-verify 2>/dev/null || true
+```
+
+9. Write prep summary artifacts (Mandatory)
+
+Write `.local/prep.md` and `.local/prep.env` for merge handoff.
+
+```sh
+contrib_id=$(gh api users/$contrib --jq .id)
+coauthor_email="${contrib_id}+${contrib}@users.noreply.github.com"
+
+cat > .local/prep.env <<EOF_ENV
+PR_NUMBER=$pr_number
+PR_AUTHOR=$contrib
+PR_HEAD=$head
+PR_HEAD_SHA_BEFORE=$pr_head_sha_before
+PREP_HEAD_SHA=$prep_head_sha
+COAUTHOR_EMAIL=$coauthor_email
+EOF_ENV
+
+ls -la .local/prep.md .local/prep.env
+wc -l .local/prep.md .local/prep.env
+```
+
+10. Output
+
+Include a diff stat summary:
+
+```sh
+git diff --stat origin/main..HEAD
+git diff --shortstat origin/main..HEAD
+```
+
+Report totals: X files changed, Y insertions(+), Z deletions(-).
+
+If gates passed and push succeeded, print exactly:
+
+```
+PR is ready for /mergepr
+```
+
+Otherwise, list remaining failures and stop.
+
+## Guardrails
+
+- Worktree only.
+- Do not delete the worktree on success. `/mergepr` may reuse it.
+- Do not run `gh pr merge`.
+- Never push to main. Only push to the PR head branch.
+- Run and pass all required gates before pushing. `pnpm test` may be skipped only for high-confidence docs-only changes, and the skip must be explicitly recorded in `.local/prep.md`.

.agents/archive/prepare-pr-v1/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prepare PR"
+  short_description: "Prepare GitHub PRs for merge"
+  default_prompt: "Use $prepare-pr to prep a GitHub PR for merge without merging."

.agents/archive/review-pr-v1/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: review-pr
+description: Review-only GitHub pull request analysis with the gh CLI. Use when asked to review a PR, provide structured feedback, or assess readiness to land. Do not merge, push, or make code changes you intend to keep.
+---
+
+# Review PR
+
+## Overview
+
+Perform a thorough review-only PR assessment and return a structured recommendation on readiness for /prepare-pr.
+
+## Inputs
+
+- Ask for PR number or URL.
+- If missing, always ask. Never auto-detect from conversation.
+- If ambiguous, ask.
+
+## Safety
+
+- Never push to `main` or `origin/main`, not during review, not ever.
+- Do not run `git push` at all during review. Treat review as read only.
+- Do not stop or kill the gateway. Do not run gateway stop commands. Do not kill processes on port 18792.
+
+## Execution Rule
+
+- Execute the workflow. Do not stop after printing the TODO checklist.
+- If delegating, require the delegate to run commands and capture outputs, not a plan.
+
+## Known Failure Modes
+
+- If you see "fatal: not a git repository", you are in the wrong directory. Move to the repository root and retry.
+- Do not stop after printing the checklist. That is not completion.
+
+## Writing Style for Output
+
+- Write casual and direct.
+- Avoid em dashes and en dashes. Use commas or separate sentences.
+
+## Completion Criteria
+
+- Run the commands in the worktree and inspect the PR directly.
+- Produce the structured review sections A through J.
+- Save the full review to `.local/review.md` inside the worktree.
+- Save PR metadata handoff to `.local/pr-meta.env` inside the worktree.
+
+## First: Create a TODO Checklist
+
+Create a checklist of all review steps, print it, then continue and execute the commands.
+
+## Setup: Use a Worktree
+
+Use an isolated worktree for all review work.
+
+```sh
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+gh auth status
+
+WORKTREE_DIR=".worktrees/pr-<PR>"
+git fetch origin main
+
+# Reuse existing worktree if it exists, otherwise create new
+if [ -d "$WORKTREE_DIR" ]; then
+  git worktree list
+  cd "$WORKTREE_DIR"
+  git fetch origin main
+  git checkout -B temp/pr-<PR> origin/main
+else
+  git worktree add "$WORKTREE_DIR" -b temp/pr-<PR> origin/main
+  cd "$WORKTREE_DIR"
+fi
+
+# Create local scratch space that persists across /review-pr to /prepare-pr to /merge-pr
+mkdir -p .local
+```
+
+Run all commands inside the worktree directory.
+Start on `origin/main` so you can check for existing implementations before looking at PR code.
+
+## Steps
+
+1. Identify PR meta and context
+
+```sh
+pr_meta_json=$(gh pr view <PR> --json number,title,state,isDraft,author,baseRefName,headRefName,headRefOid,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions,statusCheckRollup)
+printf '%s\n' "$pr_meta_json" | jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headSha:.headRefOid,headRepo:.headRepository.nameWithOwner,additions,deletions,files:(.files|length),body}'
+
+cat > .local/pr-meta.env <<EOF
+PR_NUMBER=$(printf '%s\n' "$pr_meta_json" | jq -r .number)
+PR_URL=$(printf '%s\n' "$pr_meta_json" | jq -r .url)
+PR_AUTHOR=$(printf '%s\n' "$pr_meta_json" | jq -r .author.login)
+PR_BASE=$(printf '%s\n' "$pr_meta_json" | jq -r .baseRefName)
+PR_HEAD=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefName)
+PR_HEAD_SHA=$(printf '%s\n' "$pr_meta_json" | jq -r .headRefOid)
+PR_HEAD_REPO=$(printf '%s\n' "$pr_meta_json" | jq -r .headRepository.nameWithOwner)
+EOF
+
+ls -la .local/pr-meta.env
+```
+
+2. Check if this already exists in main before looking at the PR branch
+
+- Identify the core feature or fix from the PR title and description.
+- Search for existing implementations using keywords from the PR title, changed file paths, and function or component names from the diff.
+
+```sh
+# Use keywords from the PR title and changed files
+rg -n "<keyword_from_pr_title>" -S src packages apps ui || true
+rg -n "<function_or_component_name>" -S src packages apps ui || true
+
+git log --oneline --all --grep="<keyword_from_pr_title>" | head -20
+```
+
+If it already exists, call it out as a BLOCKER or at least IMPORTANT.
+
+3. Claim the PR
+
+Assign yourself so others know someone is reviewing. Skip if the PR looks like spam or is a draft you plan to recommend closing.
+
+```sh
+gh_user=$(gh api user --jq .login)
+gh pr edit <PR> --add-assignee "$gh_user" || echo "Could not assign reviewer, continuing"
+```
+
+4. Read the PR description carefully
+
+Use the body from step 1. Summarize goal, scope, and missing context.
+
+5. Read the diff thoroughly
+
+Minimum:
+
+```sh
+gh pr diff <PR>
+```
+
+If you need full code context locally, fetch the PR head to a local ref and diff it. Do not create a merge commit.
+
+```sh
+git fetch origin pull/<PR>/head:pr-<PR> --force
+mb=$(git merge-base origin/main pr-<PR>)
+
+# Show only this PR patch relative to merge-base, not total branch drift
+git diff --stat "$mb"..pr-<PR>
+git diff "$mb"..pr-<PR>
+```
+
+If you want to browse the PR version of files directly, temporarily check out `pr-<PR>` in the worktree. Do not commit or push. Return to `temp/pr-<PR>` and reset to `origin/main` afterward.
+
+```sh
+# Use only if needed
+# git checkout pr-<PR>
+# git branch --show-current
+# ...inspect files...
+
+git checkout temp/pr-<PR>
+git checkout -B temp/pr-<PR> origin/main
+git branch --show-current
+```
+
+6. Validate the change is needed and valuable
+
+Be honest. Call out low value AI slop.
+
+7. Evaluate implementation quality
+
+Review correctness, design, performance, and ergonomics.
+
+8. Perform a security review
+
+Assume OpenClaw subagents run with full disk access, including git, gh, and shell. Check auth, input validation, secrets, dependencies, tool safety, and privacy.
+
+9. Review tests and verification
+
+Identify what exists, what is missing, and what would be a minimal regression test.
+
+If you run local tests in the worktree, bootstrap dependencies first:
+
+```sh
+if [ ! -x node_modules/.bin/vitest ]; then
+  pnpm install --frozen-lockfile
+fi
+```
+
+10. Check docs
+
+Check if the PR touches code with related documentation such as README, docs, inline API docs, or config examples.
+
+- If docs exist for the changed area and the PR does not update them, flag as IMPORTANT.
+- If the PR adds a new feature or config option with no docs, flag as IMPORTANT.
+- If the change is purely internal with no user-facing impact, skip this.
+
+11. Check changelog
+
+Check if `CHANGELOG.md` exists and whether the PR warrants an entry.
+
+- If the project has a changelog and the PR is user-facing, flag missing entry as IMPORTANT.
+- Leave the change for /prepare-pr, only flag it here.
+
+12. Answer the key question
+
+Decide if /prepare-pr can fix issues or the contributor must update the PR.
+
+13. Save findings to the worktree
+
+Write the full structured review sections A through J to `.local/review.md`.
+Create or overwrite the file and verify it exists and is non-empty.
+
+```sh
+ls -la .local/review.md
+wc -l .local/review.md
+```
+
+14. Output the structured review
+
+Produce a review that matches what you saved to `.local/review.md`.
+
+A) TL;DR recommendation
+
+- One of: READY FOR /prepare-pr | NEEDS WORK | NEEDS DISCUSSION | NOT USEFUL (CLOSE)
+- 1 to 3 sentences.
+
+B) What changed
+
+C) What is good
+
+D) Security findings
+
+E) Concerns or questions (actionable)
+
+- Numbered list.
+- Mark each item as BLOCKER, IMPORTANT, or NIT.
+- For each, point to file or area and propose a concrete fix.
+
+F) Tests
+
+G) Docs status
+
+- State if related docs are up to date, missing, or not applicable.
+
+H) Changelog
+
+- State if `CHANGELOG.md` needs an entry and which category.
+
+I) Follow ups (optional)
+
+J) Suggested PR comment (optional)
+
+## Guardrails
+
+- Worktree only.
+- Do not delete the worktree after review.
+- Review only, do not merge, do not push.

.agents/archive/review-pr-v1/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review PR"
+  short_description: "Review GitHub PRs without merging"
+  default_prompt: "Use $review-pr to perform a thorough, review-only GitHub PR review."

.agents/skills/PR_WORKFLOW.md

@@ -9,7 +9,7 @@ Process PRs **oldest to newest**. Older PRs are more likely to have merge confli
 
 ## Working rule
 
-Skills execute workflow, maintainers provide judgment.
+Skills execute workflow. Maintainers provide judgment.
 Always pause between skills to evaluate technical direction, not just command success.
 
 These three skills must be used in order:
@@ -25,6 +25,65 @@ If submitted code is low quality, ignore it and implement the best solution for
 
 Do not continue if you cannot verify the problem is real or test the fix.
 
+## Script-first contract
+
+Skill runs should invoke these wrappers automatically. You only need to run them manually when debugging or doing an explicit script-only run:
+
+- `scripts/pr-review <PR>`
+- `scripts/pr review-checkout-main <PR>` or `scripts/pr review-checkout-pr <PR>` while reviewing
+- `scripts/pr review-guard <PR>` before writing review outputs
+- `scripts/pr review-validate-artifacts <PR>` after writing outputs
+- `scripts/pr-prepare init <PR>`
+- `scripts/pr-prepare validate-commit <PR>`
+- `scripts/pr-prepare gates <PR>`
+- `scripts/pr-prepare push <PR>`
+- Optional one-shot prepare: `scripts/pr-prepare run <PR>`
+- `scripts/pr-merge <PR>` (verify-only; short form remains backward compatible)
+- `scripts/pr-merge verify <PR>` (verify-only)
+- Optional one-shot merge: `scripts/pr-merge run <PR>`
+
+These wrappers run shared preflight checks and generate deterministic artifacts. They are designed to work from repo root or PR worktree cwd.
+
+## Required artifacts
+
+- `.local/pr-meta.json` and `.local/pr-meta.env` from review init.
+- `.local/review.md` and `.local/review.json` from review output.
+- `.local/prep-context.env` and `.local/prep.md` from prepare.
+- `.local/prep.env` from prepare completion.
+
+## Structured review handoff
+
+`review-pr` must write `.local/review.json`.
+In normal skill runs this is handled automatically. Use `scripts/pr review-artifacts-init <PR>` and `scripts/pr review-tests <PR> ...` manually only for debugging or explicit script-only runs.
+
+Minimum schema:
+
+```json
+{
+  "recommendation": "READY FOR /prepare-pr",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "IMPORTANT",
+      "title": "Missing changelog entry",
+      "area": "CHANGELOG.md",
+      "fix": "Add a Fixes entry for PR #<PR>"
+    }
+  ],
+  "tests": {
+    "ran": ["pnpm test -- ..."],
+    "gaps": ["..."],
+    "result": "pass"
+  }
+}
+```
+
+`prepare-pr` resolves all `BLOCKER` and `IMPORTANT` findings from this file.
+
+## Coding Agent
+
+Use ChatGPT 5.3 Codex High. Fall back to 5.2 Codex High or 5.3 Codex Medium if necessary.
+
 ## PR quality bar
 
 - Do not trust PR code by default.
@@ -40,35 +99,52 @@ Do not continue if you cannot verify the problem is real or test the fix.
 
 Before any substantive review or prep work, **always rebase the PR branch onto current `main` and resolve merge conflicts first**. A PR that cannot cleanly rebase is not ready for review — fix conflicts before evaluating correctness.
 
-- During `prepare-pr`: rebase onto `main` is the first step, before fixing findings or running gates.
+- During `prepare-pr`: rebase onto `main` as the first step, before fixing findings or running gates.
 - If conflicts are complex or touch areas you do not understand, stop and escalate.
 - Prefer **rebase** for linear history; **squash** when commit history is messy or unhelpful.
 
 ## Commit and changelog rules
 
-- Create commits with `scripts/committer "<msg>" <file...>`; avoid manual `git add`/`git commit` so staging stays scoped.
+- In normal `prepare-pr` runs, commits are created via `scripts/committer "<msg>" <file...>`. Use it manually only when operating outside the skill flow; avoid manual `git add`/`git commit` so staging stays scoped.
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
+- During `prepare-pr`, use this commit subject format: `fix: <summary> (openclaw#<PR>) thanks @<pr-author>`.
 - Group related changes; avoid bundling unrelated refactors.
-- Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section.
-- When working on a PR: add a changelog entry with the PR number and thank the contributor.
+- Changelog workflow: keep the latest released version at the top (no `Unreleased`); after publishing, bump the version and start a new top section.
+- When working on a PR: add a changelog entry with the PR number and thank the contributor (mandatory in this workflow).
 - When working on an issue: reference the issue in the changelog entry.
-- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.
+- In this workflow, changelog is always required even for internal/test-only changes.
+
+## Gate policy
+
+In fresh worktrees, dependency bootstrap is handled by wrappers before local gates. Manual equivalent:
+
+```sh
+pnpm install --frozen-lockfile
+```
+
+Gate set:
+
+- Always: `pnpm build`, `pnpm check`
+- `pnpm test` required unless high-confidence docs-only criteria pass.
 
 ## Co-contributor and clawtributors
 
-- If we squash, add the PR author as a co-contributor in the commit.
+- If we squash, add the PR author as a co-contributor in the commit body using a `Co-authored-by:` trailer.
+- When maintainer prepares and merges the PR, add the maintainer as an additional `Co-authored-by:` trailer too.
+- Avoid `--auto` merges for maintainer landings. Merge only after checks are green so the maintainer account is the actor and attribution is deterministic.
+- For squash merges, set `--author-email` to a reviewer-owned email with fallback candidates; if merge fails due to author-email validation, retry once with the next candidate.
 - If you review a PR and later do work on it, land via merge/squash (no direct-main commits) and always add the PR author as a co-contributor.
-- When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes.
-- When merging a PR from a new contributor: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README.
+- When merging a PR: leave a PR comment that explains exactly what we did, include the SHA hashes, and record the comment URL in the final report.
+- Manual post-merge step for new contributors: run `bun scripts/update-clawtributors.ts` to add their avatar to the README "Thanks to all clawtributors" list, then commit the regenerated README.
 
 ## Review mode vs landing mode
 
 - **Review mode (PR link only):** read `gh pr view`/`gh pr diff`; **do not** switch branches; **do not** change code.
-- **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this!
+- **Landing mode (exception path):** use only when normal `review-pr -> prepare-pr -> merge-pr` flow cannot safely preserve attribution or cannot satisfy branch protection. Create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm build && pnpm check && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: the contributor needs to be in the git graph after this!
 
 ## Pre-review safety checks
 
-- Before starting a review when a GH Issue/PR is pasted: run `git pull`; if there are local changes or unpushed commits, stop and alert the user before reviewing.
+- Before starting a review when a GH Issue/PR is pasted: `review-pr`/`scripts/pr-review` should create and use an isolated `.worktrees/pr-<PR>` checkout from `origin/main` automatically. Do not require a clean main checkout, and do not run `git pull` in a dirty main checkout.
 - PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed.
 - PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
 - Read `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) for what we expect from contributors.
@@ -98,7 +174,6 @@ Maintainer checkpoint before `prepare-pr`:
 ```
 What problem are they trying to solve?
 What is the most optimal implementation?
-Is the code properly scoped?
 Can we fix up everything?
 Do we have any questions?
 ```
@@ -115,26 +190,29 @@ Purpose:
 
 - Make the PR merge-ready on its head branch.
 - Rebase onto current `main` first, then fix blocker/important findings, then run gates.
+- In fresh worktrees, bootstrap dependencies before local gates (`pnpm install --frozen-lockfile`).
 
 Expected output:
 
 - Updated code and tests on the PR head branch.
 - `.local/prep.md` with changes, verification, and current HEAD SHA.
-- Final status: `PR is ready for /mergepr`.
+- Final status: `PR is ready for /merge-pr`.
 
 Maintainer checkpoint before `merge-pr`:
 
 ```
 Is this the most optimal implementation?
 Is the code properly scoped?
+Is the code properly reusing existing logic in the codebase?
 Is the code properly typed?
 Is the code hardened?
 Do we have enough tests?
-Are tests using fake timers where relevant? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops)
+Do we need regression tests?
+Are tests using fake timers where appropriate? (e.g., debounce/throttle, retry backoff, timeout branches, delayed callbacks, polling loops)
 Do not add performative tests, ensure tests are real and there are no regressions.
-Take your time, fix it properly, refactor if necessary.
 Do you see any follow-up refactors we should do?
 Did any changes introduce any potential security vulnerabilities?
+Take your time, fix it properly, refactor if necessary.
 ```
 
 Stop and escalate instead of continuing if:
@@ -148,19 +226,21 @@ Stop and escalate instead of continuing if:
 Purpose:
 
 - Merge only after review and prep artifacts are present and checks are green.
-- Use squash merge flow and verify the PR ends in `MERGED` state.
+- Use deterministic squash merge flow (`--match-head-commit` + explicit subject/body with co-author trailer), then verify the PR ends in `MERGED` state.
+- If no required checks are configured on the PR, treat that as acceptable and continue after branch-up-to-date validation.
 
 Go or no-go checklist before merge:
 
 - All BLOCKER and IMPORTANT findings are resolved.
 - Verification is meaningful and regression risk is acceptably low.
-- Docs and changelog are updated when required.
+- Changelog is updated (mandatory) and docs are updated when required.
 - Required CI checks are green and the branch is not behind `main`.
 
 Expected output:
 
 - Successful merge commit and recorded merge SHA.
 - Worktree cleanup after successful merge.
+- Comment on PR indicating merge was successful.
 
 Maintainer checkpoint after merge:
 

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

@@ -1,187 +1,98 @@
 ---
 name: merge-pr
-description: Merge a GitHub PR via squash after /preparepr. Use when asked to merge a ready PR. Do not push to main or modify code. Ensure the PR ends in MERGED state and clean up worktrees after success.
+description: Script-first deterministic squash merge with strict required-check gating, head-SHA pinning, and reliable attribution/commenting.
 ---
 
 # Merge PR
 
 ## Overview
 
-Merge a prepared PR via `gh pr merge --squash` and clean up the worktree after success.
+Merge a prepared PR only after deterministic validation.
 
 ## Inputs
 
 - Ask for PR number or URL.
-- If missing, auto-detect from conversation.
-- If ambiguous, ask.
+- If missing, use `.local/prep.env` from the PR worktree.
 
 ## Safety
 
-- Use `gh pr merge --squash` as the only path to `main`.
-- Do not run `git push` at all during merge.
-- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
+- Never use `gh pr merge --auto` in this flow.
+- Never run `git push` directly.
+- Require `--match-head-commit` during merge.
 
-## Execution Rule
+## Execution Contract
 
-- Execute the workflow. Do not stop after printing the TODO checklist.
-- If delegating, require the delegate to run commands and capture outputs.
-
-## Known Footguns
-
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
-- Read `.local/review.md` and `.local/prep.md` in the worktree. Do not skip.
-- Clean up the real worktree directory `.worktrees/pr-<PR>` only after a successful merge.
-- Expect cleanup to remove `.local/` artifacts.
-
-## Completion Criteria
-
-- Ensure `gh pr merge` succeeds.
-- Ensure PR state is `MERGED`, never `CLOSED`.
-- Record the merge SHA.
-- Run cleanup only after merge success.
-
-## First: Create a TODO Checklist
-
-Create a checklist of all merge steps, print it, then continue and execute the commands.
-
-## Setup: Use a Worktree
-
-Use an isolated worktree for all merge work.
+1. Validate merge readiness:
 
 ```sh
-cd ~/dev/openclaw
-# Sanity: confirm you are in the repo
-git rev-parse --show-toplevel
-
-WORKTREE_DIR=".worktrees/pr-<PR>"
+scripts/pr-merge verify <PR>
 ```
 
-Run all commands inside the worktree directory.
-
-## Load Local Artifacts (Mandatory)
-
-Expect these files from earlier steps:
-
-- `.local/review.md` from `/reviewpr`
-- `.local/prep.md` from `/preparepr`
+Backward-compatible verify form also works:
 
 ```sh
-ls -la .local || true
-
-if [ -f .local/review.md ]; then
-  echo "Found .local/review.md"
-  sed -n '1,120p' .local/review.md
-else
-  echo "Missing .local/review.md. Stop and run /reviewpr, then /preparepr."
-  exit 1
-fi
-
-if [ -f .local/prep.md ]; then
-  echo "Found .local/prep.md"
-  sed -n '1,120p' .local/prep.md
-else
-  echo "Missing .local/prep.md. Stop and run /preparepr first."
-  exit 1
-fi
+scripts/pr-merge <PR>
 ```
 
+2. Run one-shot deterministic merge:
+
+```sh
+scripts/pr-merge run <PR>
+```
+
+3. Ensure output reports:
+
+- `merge_sha=<sha>`
+- `merge_author_email=<email>`
+- `comment_url=<url>`
+
 ## Steps
 
-1. Identify PR meta
+1. Validate artifacts
 
 ```sh
-gh pr view <PR> --json number,title,state,isDraft,author,headRefName,baseRefName,headRepository,body --jq '{number,title,state,isDraft,author:.author.login,head:.headRefName,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}'
-contrib=$(gh pr view <PR> --json author --jq .author.login)
-head=$(gh pr view <PR> --json headRefName --jq .headRefName)
-head_repo_url=$(gh pr view <PR> --json headRepository --jq .headRepository.url)
+require=(.local/review.md .local/review.json .local/prep.md .local/prep.env)
+for f in "${require[@]}"; do
+  [ -s "$f" ] || { echo "Missing artifact: $f"; exit 1; }
+done
 ```
 
-2. Run sanity checks
-
-Stop if any are true:
-
-- PR is a draft.
-- Required checks are failing.
-- Branch is behind main.
-
-If `.local/prep.md` contains `Docs-only change detected with high confidence; skipping pnpm test.`, that local test skip is allowed. CI checks still must be green.
+2. Validate checks and branch status
 
 ```sh
-# Checks
-gh pr checks <PR>
-
-# Check behind main
-git fetch origin main
-git fetch origin pull/<PR>/head:pr-<PR>
-git merge-base --is-ancestor origin/main pr-<PR> || echo "PR branch is behind main, run /preparepr"
+scripts/pr-merge verify <PR>
+source .local/prep.env
 ```
 
-If anything is failing or behind, stop and say to run `/preparepr`.
+`scripts/pr-merge` treats “no required checks configured” as acceptable (`[]`), but fails on any required `fail` or `pending`.
 
-3. Merge PR and delete branch
-
-If checks are still running, use `--auto` to queue the merge.
+3. Merge deterministically (wrapper-managed)
 
 ```sh
-# Check status first
-check_status=$(gh pr checks <PR> 2>&1)
-if echo "$check_status" | grep -q "pending\|queued"; then
-  echo "Checks still running, using --auto to queue merge"
-  gh pr merge <PR> --squash --delete-branch --auto
-  echo "Merge queued. Monitor with: gh pr checks <PR> --watch"
-else
-  gh pr merge <PR> --squash --delete-branch
-fi
+scripts/pr-merge run <PR>
 ```
 
-If merge fails, report the error and stop. Do not retry in a loop.
-If the PR needs changes beyond what `/preparepr` already did, stop and say to run `/preparepr` again.
+`scripts/pr-merge run` performs:
 
-4. Get merge SHA
+- deterministic squash merge pinned to `PREP_HEAD_SHA`
+- reviewer merge author email selection with fallback candidates
+- one retry only when merge fails due to author-email validation
+- co-author trailers for PR author and reviewer
+- post-merge verification of both co-author trailers on commit message
+- PR comment retry (3 attempts), then comment URL extraction
+- cleanup after confirmed `MERGED`
+
+4. Manual fallback (only if wrapper is unavailable)
 
 ```sh
-merge_sha=$(gh pr view <PR> --json mergeCommit --jq '.mergeCommit.oid')
-echo "merge_sha=$merge_sha"
+scripts/pr merge-run <PR>
 ```
 
-5. Optional comment
+5. Cleanup
 
-Use a literal multiline string or heredoc for newlines.
-
-```sh
-gh pr comment <PR> -F - <<'EOF'
-Merged via squash.
-
-- Merge commit: $merge_sha
-
-Thanks @$contrib!
-EOF
-```
-
-6. Verify PR state is MERGED
-
-```sh
-gh pr view <PR> --json state --jq .state
-```
-
-7. Clean up worktree only on success
-
-Run cleanup only if step 6 returned `MERGED`.
-
-```sh
-cd ~/dev/openclaw
-
-git worktree remove ".worktrees/pr-<PR>" --force
-
-git branch -D temp/pr-<PR> 2>/dev/null || true
-git branch -D pr-<PR> 2>/dev/null || true
-```
+Cleanup is handled by `run` after merge success.
 
 ## Guardrails
 
-- Worktree only.
-- Do not close PRs.
-- End in MERGED state.
-- Clean up only after merge success.
-- Never push to main. Use `gh pr merge --squash` only.
-- Do not run `git push` at all in this command.
+- End in `MERGED`, never `CLOSED`.
+- Cleanup only after confirmed merge.

.agents/skills/mintlify/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: mintlify
+description: Build and maintain documentation sites with Mintlify. Use when
+  creating docs pages, configuring navigation, adding components, or setting up
+  API references.
+license: MIT
+compatibility: Requires Node.js for CLI. Works with any Git-based workflow.
+metadata:
+  author: mintlify
+  version: "1.0"
+  mintlify-proj: mintlify
+---
+
+# Mintlify best practices
+
+**Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.**
+
+**Always** favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.
+
+Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.
+
+Full schema at [mintlify.com/docs.json](https://mintlify.com/docs.json).
+
+## Before you write
+
+### Understand the project
+
+All documentation lives in the `docs/` directory in this repo. Read `docs.json` in that directory (`docs/docs.json`). This file defines the entire site: navigation structure, theme, colors, links, API and specs.
+
+Understanding the project tells you:
+
+- What pages exist and how they're organized
+- What navigation groups are used (and their naming conventions)
+- How the site navigation is structured
+- What theme and configuration the site uses
+
+### Check for existing content
+
+Search the docs before creating new pages. You may need to:
+
+- Update an existing page instead of creating a new one
+- Add a section to an existing page
+- Link to existing content rather than duplicating
+
+### Read surrounding content
+
+Before writing, read 2-3 similar pages to understand the site's voice, structure, formatting conventions, and level of detail.
+
+### Understand Mintlify components
+
+Review the Mintlify [components](https://www.mintlify.com/docs/components) to select and use any relevant components for the documentation request that you are working on.
+
+## Quick reference
+
+### CLI commands
+
+- `npm i -g mint` - Install the Mintlify CLI
+- `mint dev` - Local preview at localhost:3000
+- `mint broken-links` - Check internal links
+- `mint a11y` - Check for accessibility issues in content
+- `mint rename` - Rename/move files and update references
+- `mint validate` - Validate documentation builds
+
+### Required files
+
+- `docs.json` - Site configuration (navigation, theme, integrations, etc.). See [global settings](https://mintlify.com/docs/settings/global) for all options.
+- `*.mdx` files - Documentation pages with YAML frontmatter
+
+### Example file structure
+
+```
+project/
+├── docs.json           # Site configuration
+├── introduction.mdx
+├── quickstart.mdx
+├── guides/
+│   └── example.mdx
+├── openapi.yml         # API specification
+├── images/             # Static assets
+│   └── example.png
+└── snippets/           # Reusable components
+    └── component.jsx
+```
+
+## Page frontmatter
+
+Every page requires `title` in its frontmatter. Include `description` for SEO and navigation.
+
+```yaml theme={null}
+---
+title: "Clear, descriptive title"
+description: "Concise summary for SEO and navigation."
+---
+```
+
+Optional frontmatter fields:
+
+- `sidebarTitle`: Short title for sidebar navigation.
+- `icon`: Lucide or Font Awesome icon name, URL, or file path.
+- `tag`: Label next to the page title in the sidebar (for example, "NEW").
+- `mode`: Page layout mode (`default`, `wide`, `custom`).
+- `keywords`: Array of terms related to the page content for local search and SEO.
+- Any custom YAML fields for use with personalization or conditional content.
+
+## File conventions
+
+- Match existing naming patterns in the directory
+- If there are no existing files or inconsistent file naming patterns, use kebab-case: `getting-started.mdx`, `api-reference.mdx`
+- Use root-relative paths without file extensions for internal links: `/getting-started/quickstart`
+- Do not use relative paths (`../`) or absolute URLs for internal pages
+- When you create a new page, add it to `docs.json` navigation or it won't appear in the sidebar
+
+## Organize content
+
+When a user asks about anything related to site-wide configurations, start by understanding the [global settings](https://www.mintlify.com/docs/organize/settings). See if a setting in the `docs.json` file can be updated to achieve what the user wants.
+
+### Navigation
+
+The `navigation` property in `docs.json` controls site structure. Choose one primary pattern at the root level, then nest others within it.
+
+**Choose your primary pattern:**
+
+| Pattern       | When to use                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------------- |
+| **Groups**    | Default. Single audience, straightforward hierarchy                                            |
+| **Tabs**      | Distinct sections with different audiences (Guides vs API Reference) or content types          |
+| **Anchors**   | Want persistent section links at sidebar top. Good for separating docs from external resources |
+| **Dropdowns** | Multiple doc sections users switch between, but not distinct enough for tabs                   |
+| **Products**  | Multi-product company with separate documentation per product                                  |
+| **Versions**  | Maintaining docs for multiple API/product versions simultaneously                              |
+| **Languages** | Localized content                                                                              |
+
+**Within your primary pattern:**
+
+- **Groups** - Organize related pages. Can nest groups within groups, but keep hierarchy shallow
+- **Menus** - Add dropdown navigation within tabs for quick jumps to specific pages
+- **`expanded: false`** - Collapse nested groups by default. Use for reference sections users browse selectively
+- **`openapi`** - Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit
+
+**Common combinations:**
+
+- Tabs containing groups (most common for docs with API reference)
+- Products containing tabs (multi-product SaaS)
+- Versions containing tabs (versioned API docs)
+- Anchors containing groups (simple docs with external resource links)
+
+### Links and paths
+
+- **Internal links:** Root-relative, no extension: `/getting-started/quickstart`
+- **Images:** Store in `/images`, reference as `/images/example.png`
+- **External links:** Use full URLs, they open in new tabs automatically
+
+## Customize docs sites
+
+**What to customize where:**
+
+- **Brand colors, fonts, logo** → `docs.json`. See [global settings](https://mintlify.com/docs/settings/global)
+- **Component styling, layout tweaks** → `custom.css` at project root
+- **Dark mode** → Enabled by default. Only disable with `"appearance": "light"` in `docs.json` if brand requires it
+
+Start with `docs.json`. Only add `custom.css` when you need styling that config doesn't support.
+
+## Write content
+
+### Components
+
+The [components overview](https://mintlify.com/docs/components) organizes all components by purpose: structure content, draw attention, show/hide content, document APIs, link to pages, and add visual context. Start there to find the right component.
+
+**Common decision points:**
+
+| Need                       | Use                     |
+| -------------------------- | ----------------------- |
+| Hide optional details      | `<Accordion>`           |
+| Long code examples         | `<Expandable>`          |
+| User chooses one option    | `<Tabs>`                |
+| Linked navigation cards    | `<Card>` in `<Columns>` |
+| Sequential instructions    | `<Steps>`               |
+| Code in multiple languages | `<CodeGroup>`           |
+| API parameters             | `<ParamField>`          |
+| API response fields        | `<ResponseField>`       |
+
+**Callouts by severity:**
+
+- `<Note>` - Supplementary info, safe to skip
+- `<Info>` - Helpful context such as permissions
+- `<Tip>` - Recommendations or best practices
+- `<Warning>` - Potentially destructive actions
+- `<Check>` - Success confirmation
+
+### Reusable content
+
+**When to use snippets:**
+
+- Exact content appears on more than one page
+- Complex components you want to maintain in one place
+- Shared content across teams/repos
+
+**When NOT to use snippets:**
+
+- Slight variations needed per page (leads to complex props)
+
+Import snippets with `import { Component } from "/path/to/snippet-name.jsx"`.
+
+## Writing standards
+
+### Voice and structure
+
+- Second-person voice ("you")
+- Active voice, direct language
+- Sentence case for headings ("Getting started", not "Getting Started")
+- Sentence case for code block titles ("Expandable example", not "Expandable Example")
+- Lead with context: explain what something is before how to use it
+- Prerequisites at the start of procedural content
+
+### What to avoid
+
+**Never use:**
+
+- Marketing language ("powerful", "seamless", "robust", "cutting-edge")
+- Filler phrases ("it's important to note", "in order to")
+- Excessive conjunctions ("moreover", "furthermore", "additionally")
+- Editorializing ("obviously", "simply", "just", "easily")
+
+**Watch for AI-typical patterns:**
+
+- Overly formal or stilted phrasing
+- Unnecessary repetition of concepts
+- Generic introductions that don't add value
+- Concluding summaries that restate what was just said
+
+### Formatting
+
+- All code blocks must have language tags
+- All images and media must have descriptive alt text
+- Use bold and italics only when they serve the reader's understanding--never use text styling just for decoration
+- No decorative formatting or emoji
+
+### Code examples
+
+- Keep examples simple and practical
+- Use realistic values (not "foo" or "bar")
+- One clear example is better than multiple variations
+- Test that code works before including it
+
+## Document APIs
+
+**Choose your approach:**
+
+- **Have an OpenAPI spec?** → Add to `docs.json` with `"openapi": ["openapi.yaml"]`. Pages auto-generate. Reference in navigation as `GET /endpoint`
+- **No spec?** → Write endpoints manually with `api: "POST /users"` in frontmatter. More work but full control
+- **Hybrid** → Use OpenAPI for most endpoints, manual pages for complex workflows
+
+Encourage users to generate endpoint pages from an OpenAPI spec. It is the most efficient and easiest to maintain option.
+
+## Deploy
+
+Mintlify deploys automatically when changes are pushed to the connected Git repository.
+
+**What agents can configure:**
+
+- **Redirects** → Add to `docs.json` with `"redirects": [{"source": "/old", "destination": "/new"}]`
+- **SEO indexing** → Control with `"seo": {"indexing": "all"}` to include hidden pages in search
+
+**Requires dashboard setup (human task):**
+
+- Custom domains and subdomains
+- Preview deployment settings
+- DNS configuration
+
+For `/docs` subpath hosting with Vercel or Cloudflare, agents can help configure rewrite rules. See [/docs subpath](https://mintlify.com/docs/deploy/vercel).
+
+## Workflow
+
+### 1. Understand the task
+
+Identify what needs to be documented, which pages are affected, and what the reader should accomplish afterward. If any of these are unclear, ask.
+
+### 2. Research
+
+- Read `docs/docs.json` to understand the site structure
+- Search existing docs for related content
+- Read similar pages to match the site's style
+
+### 3. Plan
+
+- Synthesize what the reader should accomplish after reading the docs and the current content
+- Propose any updates or new content
+- Verify that your proposed changes will help readers be successful
+
+### 4. Write
+
+- Start with the most important information
+- Keep sections focused and scannable
+- Use components appropriately (don't overuse them)
+- Mark anything uncertain with a TODO comment:
+
+```mdx theme={null}
+{/* TODO: Verify the default timeout value */}
+```
+
+### 5. Update navigation
+
+If you created a new page, add it to the appropriate group in `docs.json`.
+
+### 6. Verify
+
+Before submitting:
+
+- [ ] Frontmatter includes title and description
+- [ ] All code blocks have language tags
+- [ ] Internal links use root-relative paths without file extensions
+- [ ] New pages are added to `docs.json` navigation
+- [ ] Content matches the style of surrounding pages
+- [ ] No marketing language or filler phrases
+- [ ] TODOs are clearly marked for anything uncertain
+- [ ] Run `mint broken-links` to check links
+- [ ] Run `mint validate` to find any errors
+
+## Edge cases
+
+### Migrations
+
+If a user asks about migrating to Mintlify, ask if they are using ReadMe or Docusaurus. If they are, use the [@mintlify/scraping](https://www.npmjs.com/package/@mintlify/scraping) CLI to migrate content. If they are using a different platform to host their documentation, help them manually convert their content to MDX pages using Mintlify components.
+
+### Hidden pages
+
+Any page that is not included in the `docs.json` navigation is hidden. Use hidden pages for content that should be accessible by URL or indexed for the assistant or search, but not discoverable through the sidebar navigation.
+
+### Exclude pages
+
+The `.mintignore` file is used to exclude files from a documentation repository from being processed.
+
+## Common gotchas
+
+1. **Component imports** - JSX components need explicit import, MDX components don't
+2. **Frontmatter required** - Every MDX file needs `title` at minimum
+3. **Code block language** - Always specify language identifier
+4. **Never use `mint.json`** - `mint.json` is deprecated. Only ever use `docs.json`
+
+## Resources
+
+- [Documentation](https://mintlify.com/docs)
+- [Configuration schema](https://mintlify.com/docs.json)
+- [Feature requests](https://github.com/orgs/mintlify/discussions/categories/feature-requests)
+- [Bugs and feedback](https://github.com/orgs/mintlify/discussions/categories/bugs-feedback)

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

@@ -1,277 +1,131 @@
 ---
 name: prepare-pr
-description: Prepare a GitHub PR for merge by rebasing onto main, fixing review findings, running gates, committing fixes, and pushing to the PR head branch. Use after /reviewpr. Never merge or push to main.
+description: Script-first PR preparation with structured findings resolution, deterministic push safety, and explicit gate execution.
 ---
 
 # Prepare PR
 
 ## Overview
 
-Prepare a PR branch for merge with review fixes, green gates, and an updated head branch.
+Prepare the PR head branch for merge after `/review-pr`.
 
 ## Inputs
 
 - Ask for PR number or URL.
-- If missing, auto-detect from conversation.
-- If ambiguous, ask.
+- If missing, use `.local/pr-meta.env` if present in the PR worktree.
 
 ## Safety
 
-- Never push to `main` or `origin/main`. Push only to the PR head branch.
-- Never run `git push` without specifying remote and branch explicitly. Do not run bare `git push`.
-- Do not run gateway stop commands. Do not kill processes. Do not touch port 18792.
+- Never push to `main`.
+- Only push to PR head with explicit `--force-with-lease` against known head SHA.
 - Do not run `git clean -fdx`.
-- Do not run `git add -A` or `git add .`. Stage only specific files changed.
+- Wrappers are cwd-agnostic; run from repo root or PR worktree.
 
-## Execution Rule
+## Execution Contract
 
-- Execute the workflow. Do not stop after printing the TODO checklist.
-- If delegating, require the delegate to run commands and capture outputs.
-
-## Known Footguns
-
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
-- Do not run `git clean -fdx`.
-- Do not run `git add -A` or `git add .`.
-
-## Completion Criteria
-
-- Rebase PR commits onto `origin/main`.
-- Fix all BLOCKER and IMPORTANT items from `.local/review.md`.
-- Run required gates and pass (docs-only PRs may skip `pnpm test` when high-confidence docs-only criteria are met and documented).
-- Commit prep changes.
-- Push the updated HEAD back to the PR head branch.
-- Write `.local/prep.md` with a prep summary.
-- Output exactly: `PR is ready for /mergepr`.
-
-## First: Create a TODO Checklist
-
-Create a checklist of all prep steps, print it, then continue and execute the commands.
-
-## Setup: Use a Worktree
-
-Use an isolated worktree for all prep work.
+1. Run setup:
 
 ```sh
-cd ~/openclaw
-# Sanity: confirm you are in the repo
-git rev-parse --show-toplevel
-
-WORKTREE_DIR=".worktrees/pr-<PR>"
+scripts/pr-prepare init <PR>
 ```
 
-Run all commands inside the worktree directory.
+2. Resolve findings from structured review:
 
-## Load Review Findings (Mandatory)
+- `.local/review.json` is mandatory.
+- Resolve all `BLOCKER` and `IMPORTANT` items.
+
+3. Commit with required subject format and validate it.
+
+4. Run gates via wrapper.
+
+5. Push via wrapper (includes pre-push remote verification, one automatic lease-retry path, and post-push API propagation retry).
+
+Optional one-shot path:
 
 ```sh
-if [ -f .local/review.md ]; then
-  echo "Found review findings from /reviewpr"
-else
-  echo "Missing .local/review.md. Run /reviewpr first and save findings."
-  exit 1
-fi
-
-# Read it
-sed -n '1,200p' .local/review.md
+scripts/pr-prepare run <PR>
 ```
 
 ## Steps
 
-1. Identify PR meta (author, head branch, head repo URL)
+1. Setup and artifacts
 
 ```sh
-gh pr view <PR> --json number,title,author,headRefName,baseRefName,headRepository,body --jq '{number,title,author:.author.login,head:.headRefName,base:.baseRefName,headRepo:.headRepository.nameWithOwner,body}'
-contrib=$(gh pr view <PR> --json author --jq .author.login)
-head=$(gh pr view <PR> --json headRefName --jq .headRefName)
-head_repo_url=$(gh pr view <PR> --json headRepository --jq .headRepository.url)
+scripts/pr-prepare init <PR>
+
+ls -la .local/review.md .local/review.json .local/pr-meta.env .local/prep-context.env
+jq . .local/review.json >/dev/null
 ```
 
-2. Fetch the PR branch tip into a local ref
+2. Resolve required findings
+
+List required items:
 
 ```sh
-git fetch origin pull/<PR>/head:pr-<PR>
+jq -r '.findings[] | select(.severity=="BLOCKER" or .severity=="IMPORTANT") | "- [\(.severity)] \(.id): \(.title) => \(.fix)"' .local/review.json
 ```
 
-3. Rebase PR commits onto latest main
+Fix all required findings. Keep scope tight.
+
+3. Update changelog/docs (changelog is mandatory in this workflow)
 
 ```sh
-# Move worktree to the PR tip first
-git reset --hard pr-<PR>
-
-# Rebase onto current main
-git fetch origin main
-git rebase origin/main
+jq -r '.changelog' .local/review.json
+jq -r '.docs' .local/review.json
 ```
 
-If conflicts happen:
+4. Commit scoped changes
 
-- Resolve each conflicted file.
-- Run `git add <resolved_file>` for each file.
-- Run `git rebase --continue`.
+Required commit subject format:
 
-If the rebase gets confusing or you resolve conflicts 3 or more times, stop and report.
+- `fix: <summary> (openclaw#<PR>) thanks @<pr-author>`
 
-4. Fix issues from `.local/review.md`
-
-- Fix all BLOCKER and IMPORTANT items.
-- NITs are optional.
-- Keep scope tight.
-
-Keep a running log in `.local/prep.md`:
-
-- List which review items you fixed.
-- List which files you touched.
-- Note behavior changes.
-
-5. Update `CHANGELOG.md` if flagged in review
-
-Check `.local/review.md` section H for guidance.
-If flagged and user-facing:
-
-- Check if `CHANGELOG.md` exists.
+Use explicit file list:
 
 ```sh
-ls CHANGELOG.md 2>/dev/null
+source .local/pr-meta.env
+scripts/committer "fix: <summary> (openclaw#$PR_NUMBER) thanks @$PR_AUTHOR" <file1> <file2> ...
 ```
 
-- Follow existing format.
-- Add a concise entry with PR number and contributor.
-
-6. Update docs if flagged in review
-
-Check `.local/review.md` section G for guidance.
-If flagged, update only docs related to the PR changes.
-
-7. Commit prep fixes
-
-Stage only specific files:
+Validate commit subject:
 
 ```sh
-git add <file1> <file2> ...
+scripts/pr-prepare validate-commit <PR>
 ```
 
-Preferred commit tool:
+5. Run gates
 
 ```sh
-committer "fix: <summary> (#<PR>) (thanks @$contrib)" <changed files>
+scripts/pr-prepare gates <PR>
 ```
 
-If `committer` is not found:
+6. Push safely to PR head
 
 ```sh
-git commit -m "fix: <summary> (#<PR>) (thanks @$contrib)"
+scripts/pr-prepare push <PR>
 ```
 
-8. Decide verification mode and run required gates before pushing
+This push step includes:
 
-If you are highly confident the change is docs-only, you may skip `pnpm test`.
+- robust fork remote resolution from owner/name,
+- pre-push remote SHA verification,
+- one automatic rebase + gate rerun + retry if lease push fails,
+- post-push PR-head propagation retry,
+- idempotent behavior when local prep HEAD is already on the PR head,
+- post-push SHA verification and `.local/prep.env` generation.
 
-High-confidence docs-only criteria (all must be true):
-
-- Every changed file is documentation-only (`docs/**`, `README*.md`, `CHANGELOG.md`, `*.md`, `*.mdx`, `mintlify.json`, `docs.json`).
-- No code, runtime, test, dependency, or build config files changed (`src/**`, `extensions/**`, `apps/**`, `package.json`, lockfiles, TS/JS config, test files, scripts).
-- `.local/review.md` does not call for non-doc behavior fixes.
-
-Suggested check:
+7. Verify handoff artifacts
 
 ```sh
-changed_files=$(git diff --name-only origin/main...HEAD)
-non_docs=$(printf "%s\n" "$changed_files" | grep -Ev '^(docs/|README.*\.md$|CHANGELOG\.md$|.*\.md$|.*\.mdx$|mintlify\.json$|docs\.json$)' || true)
-
-docs_only=false
-if [ -n "$changed_files" ] && [ -z "$non_docs" ]; then
-  docs_only=true
-fi
-
-echo "docs_only=$docs_only"
+ls -la .local/prep.md .local/prep.env
 ```
 
-Run required gates:
+8. Output
 
-```sh
-pnpm install
-pnpm build
-pnpm ui:build
-pnpm check
-
-if [ "$docs_only" = "true" ]; then
-  echo "Docs-only change detected with high confidence; skipping pnpm test." | tee -a .local/prep.md
-else
-  pnpm test
-fi
-```
-
-Require all required gates to pass. If something fails, fix, commit, and rerun. Allow at most 3 fix and rerun cycles. If gates still fail after 3 attempts, stop and report the failures. Do not loop indefinitely.
-
-9. Push updates back to the PR head branch
-
-```sh
-# Ensure remote for PR head exists
-git remote add prhead "$head_repo_url.git" 2>/dev/null || git remote set-url prhead "$head_repo_url.git"
-
-# Use force with lease after rebase
-# Double check: $head must NOT be "main" or "master"
-echo "Pushing to branch: $head"
-if [ "$head" = "main" ] || [ "$head" = "master" ]; then
-  echo "ERROR: head branch is main/master. This is wrong. Stopping."
-  exit 1
-fi
-git push --force-with-lease prhead HEAD:$head
-```
-
-10. Verify PR is not behind main (Mandatory)
-
-```sh
-git fetch origin main
-git fetch origin pull/<PR>/head:pr-<PR>-verify --force
-git merge-base --is-ancestor origin/main pr-<PR>-verify && echo "PR is up to date with main" || echo "ERROR: PR is still behind main, rebase again"
-git branch -D pr-<PR>-verify 2>/dev/null || true
-```
-
-If still behind main, repeat steps 2 through 9.
-
-11. Write prep summary artifacts (Mandatory)
-
-Update `.local/prep.md` with:
-
-- Current HEAD sha from `git rev-parse HEAD`.
-- Short bullet list of changes.
-- Gate results.
-- Push confirmation.
-- Rebase verification result.
-
-Create or overwrite `.local/prep.md` and verify it exists and is non-empty:
-
-```sh
-git rev-parse HEAD
-ls -la .local/prep.md
-wc -l .local/prep.md
-```
-
-12. Output
-
-Include a diff stat summary:
-
-```sh
-git diff --stat origin/main..HEAD
-git diff --shortstat origin/main..HEAD
-```
-
-Report totals: X files changed, Y insertions(+), Z deletions(-).
-
-If gates passed and push succeeded, print exactly:
-
-```
-PR is ready for /mergepr
-```
-
-Otherwise, list remaining failures and stop.
+- Summarize resolved findings and gate results.
+- Print exactly: `PR is ready for /merge-pr`.
 
 ## Guardrails
 
-- Worktree only.
-- Do not delete the worktree on success. `/mergepr` may reuse it.
-- Do not run `gh pr merge`.
-- Never push to main. Only push to the PR head branch.
-- Run and pass all required gates before pushing. `pnpm test` may be skipped only for high-confidence docs-only changes, and the skip must be explicitly recorded in `.local/prep.md`.
+- Do not run `gh pr merge` in this skill.
+- Do not delete worktree.

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

@@ -1,228 +1,141 @@
 ---
 name: review-pr
-description: Review-only GitHub pull request analysis with the gh CLI. Use when asked to review a PR, provide structured feedback, or assess readiness to land. Do not merge, push, or make code changes you intend to keep.
+description: Script-first review-only GitHub pull request analysis. Use for deterministic PR review with structured findings handoff to /prepare-pr.
 ---
 
 # Review PR
 
 ## Overview
 
-Perform a thorough review-only PR assessment and return a structured recommendation on readiness for /preparepr.
+Perform a read-only review and produce both human and machine-readable outputs.
 
 ## Inputs
 
 - Ask for PR number or URL.
-- If missing, always ask. Never auto-detect from conversation.
-- If ambiguous, ask.
+- If missing, always ask.
 
 ## Safety
 
-- Never push to `main` or `origin/main`, not during review, not ever.
-- Do not run `git push` at all during review. Treat review as read only.
-- Do not stop or kill the gateway. Do not run gateway stop commands. Do not kill processes on port 18792.
+- Never push, merge, or modify code intended to keep.
+- Work only in `.worktrees/pr-<PR>`.
 
-## Execution Rule
+## Execution Contract
 
-- Execute the workflow. Do not stop after printing the TODO checklist.
-- If delegating, require the delegate to run commands and capture outputs, not a plan.
-
-## Known Failure Modes
-
-- If you see "fatal: not a git repository", you are in the wrong directory. Use `~/dev/openclaw` if available; otherwise ask user.
-- Do not stop after printing the checklist. That is not completion.
-
-## Writing Style for Output
-
-- Write casual and direct.
-- Avoid em dashes and en dashes. Use commas or separate sentences.
-
-## Completion Criteria
-
-- Run the commands in the worktree and inspect the PR directly.
-- Produce the structured review sections A through J.
-- Save the full review to `.local/review.md` inside the worktree.
-
-## First: Create a TODO Checklist
-
-Create a checklist of all review steps, print it, then continue and execute the commands.
-
-## Setup: Use a Worktree
-
-Use an isolated worktree for all review work.
+1. Run wrapper setup:
 
 ```sh
-cd ~/dev/openclaw
-# Sanity: confirm you are in the repo
-git rev-parse --show-toplevel
-
-WORKTREE_DIR=".worktrees/pr-<PR>"
-git fetch origin main
-
-# Reuse existing worktree if it exists, otherwise create new
-if [ -d "$WORKTREE_DIR" ]; then
-  cd "$WORKTREE_DIR"
-  git checkout temp/pr-<PR> 2>/dev/null || git checkout -b temp/pr-<PR>
-  git fetch origin main
-  git reset --hard origin/main
-else
-  git worktree add "$WORKTREE_DIR" -b temp/pr-<PR> origin/main
-  cd "$WORKTREE_DIR"
-fi
-
-# Create local scratch space that persists across /reviewpr to /preparepr to /mergepr
-mkdir -p .local
+scripts/pr-review <PR>
 ```
 
-Run all commands inside the worktree directory.
-Start on `origin/main` so you can check for existing implementations before looking at PR code.
+2. Use explicit branch mode switches:
+
+- Main baseline mode: `scripts/pr review-checkout-main <PR>`
+- PR-head mode: `scripts/pr review-checkout-pr <PR>`
+
+3. Before writing review outputs, run branch guard:
+
+```sh
+scripts/pr review-guard <PR>
+```
+
+4. Write both outputs:
+
+- `.local/review.md` with sections A through J.
+- `.local/review.json` with structured findings.
+
+5. Validate artifacts semantically:
+
+```sh
+scripts/pr review-validate-artifacts <PR>
+```
 
 ## Steps
 
-1. Identify PR meta and context
+1. Setup and metadata
 
 ```sh
-gh pr view <PR> --json number,title,state,isDraft,author,baseRefName,headRefName,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions --jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headRepo:.headRepository.nameWithOwner,additions,deletions,files:.files|length,body}'
+scripts/pr-review <PR>
+ls -la .local/pr-meta.json .local/pr-meta.env .local/review-context.env .local/review-mode.env
 ```
 
-2. Check if this already exists in main before looking at the PR branch
-
-- Identify the core feature or fix from the PR title and description.
-- Search for existing implementations using keywords from the PR title, changed file paths, and function or component names from the diff.
+2. Existing implementation check on main
 
 ```sh
-# Use keywords from the PR title and changed files
-rg -n "<keyword_from_pr_title>" -S src packages apps ui || true
-rg -n "<function_or_component_name>" -S src packages apps ui || true
-
-git log --oneline --all --grep="<keyword_from_pr_title>" | head -20
+scripts/pr review-checkout-main <PR>
+rg -n "<keyword>" -S src extensions apps || true
+git log --oneline --all --grep "<keyword>" | head -20
 ```
 
-If it already exists, call it out as a BLOCKER or at least IMPORTANT.
-
-3. Claim the PR
-
-Assign yourself so others know someone is reviewing. Skip if the PR looks like spam or is a draft you plan to recommend closing.
+3. Claim PR
 
 ```sh
 gh_user=$(gh api user --jq .login)
-gh pr edit <PR> --add-assignee "$gh_user"
+gh pr edit <PR> --add-assignee "$gh_user" || echo "Could not assign reviewer, continuing"
 ```
 
-4. Read the PR description carefully
-
-Use the body from step 1. Summarize goal, scope, and missing context.
-
-5. Read the diff thoroughly
-
-Minimum:
+4. Read PR description and diff
 
 ```sh
+scripts/pr review-checkout-pr <PR>
 gh pr diff <PR>
+
+source .local/review-context.env
+git diff --stat "$MERGE_BASE"..pr-<PR>
+git diff "$MERGE_BASE"..pr-<PR>
 ```
 
-If you need full code context locally, fetch the PR head to a local ref and diff it. Do not create a merge commit.
+5. Optional local tests
+
+Use the wrapper for target validation and executed-test verification:
 
 ```sh
-git fetch origin pull/<PR>/head:pr-<PR>
-# Show changes without modifying the working tree
-
-git diff --stat origin/main..pr-<PR>
-git diff origin/main..pr-<PR>
+scripts/pr review-tests <PR> <test-file> [<test-file> ...]
 ```
 
-If you want to browse the PR version of files directly, temporarily check out `pr-<PR>` in the worktree. Do not commit or push. Return to `temp/pr-<PR>` and reset to `origin/main` afterward.
+6. Initialize review artifact templates
 
 ```sh
-# Use only if needed
-# git checkout pr-<PR>
-# ...inspect files...
-
-git checkout temp/pr-<PR>
-git reset --hard origin/main
+scripts/pr review-artifacts-init <PR>
 ```
 
-6. Validate the change is needed and valuable
+7. Produce review outputs
 
-Be honest. Call out low value AI slop.
+- Fill `.local/review.md` sections A through J.
+- Fill `.local/review.json`.
 
-7. Evaluate implementation quality
+Minimum JSON shape:
 
-Review correctness, design, performance, and ergonomics.
+```json
+{
+  "recommendation": "READY FOR /prepare-pr",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "IMPORTANT",
+      "title": "...",
+      "area": "path/or/component",
+      "fix": "Actionable fix"
+    }
+  ],
+  "tests": {
+    "ran": [],
+    "gaps": [],
+    "result": "pass"
+  },
+  "docs": "up_to_date|missing|not_applicable",
+  "changelog": "required"
+}
+```
 
-8. Perform a security review
-
-Assume OpenClaw subagents run with full disk access, including git, gh, and shell. Check auth, input validation, secrets, dependencies, tool safety, and privacy.
-
-9. Review tests and verification
-
-Identify what exists, what is missing, and what would be a minimal regression test.
-
-10. Check docs
-
-Check if the PR touches code with related documentation such as README, docs, inline API docs, or config examples.
-
-- If docs exist for the changed area and the PR does not update them, flag as IMPORTANT.
-- If the PR adds a new feature or config option with no docs, flag as IMPORTANT.
-- If the change is purely internal with no user-facing impact, skip this.
-
-11. Check changelog
-
-Check if `CHANGELOG.md` exists and whether the PR warrants an entry.
-
-- If the project has a changelog and the PR is user-facing, flag missing entry as IMPORTANT.
-- Leave the change for /preparepr, only flag it here.
-
-12. Answer the key question
-
-Decide if /preparepr can fix issues or the contributor must update the PR.
-
-13. Save findings to the worktree
-
-Write the full structured review sections A through J to `.local/review.md`.
-Create or overwrite the file and verify it exists and is non-empty.
+8. Guard + validate before final output
 
 ```sh
-ls -la .local/review.md
-wc -l .local/review.md
+scripts/pr review-guard <PR>
+scripts/pr review-validate-artifacts <PR>
 ```
 
-14. Output the structured review
-
-Produce a review that matches what you saved to `.local/review.md`.
-
-A) TL;DR recommendation
-
-- One of: READY FOR /preparepr | NEEDS WORK | NEEDS DISCUSSION | NOT USEFUL (CLOSE)
-- 1 to 3 sentences.
-
-B) What changed
-
-C) What is good
-
-D) Security findings
-
-E) Concerns or questions (actionable)
-
-- Numbered list.
-- Mark each item as BLOCKER, IMPORTANT, or NIT.
-- For each, point to file or area and propose a concrete fix.
-
-F) Tests
-
-G) Docs status
-
-- State if related docs are up to date, missing, or not applicable.
-
-H) Changelog
-
-- State if `CHANGELOG.md` needs an entry and which category.
-
-I) Follow ups (optional)
-
-J) Suggested PR comment (optional)
-
 ## Guardrails
 
-- Worktree only.
-- Do not delete the worktree after review.
-- Review only, do not merge, do not push.
+- Keep review read-only.
+- Do not delete worktree.
+- Use merge-base scoped diff for local context to avoid stale branch drift.

.github/labeler.yml

@@ -9,6 +9,11 @@
           - "src/discord/**"
           - "extensions/discord/**"
           - "docs/channels/discord.md"
+"channel: irc":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/irc/**"
+          - "docs/channels/irc.md"
 "channel: feishu":
   - changed-files:
       - any-glob-to-any-file:

.github/workflows/auto-response.yml

@@ -60,22 +60,47 @@ jobs:
               },
             ];
 
+            const triggerLabel = "trigger-response";
+            const target = context.payload.issue ?? context.payload.pull_request;
+            if (!target) {
+              return;
+            }
+
+            const labelSet = new Set(
+              (target.labels ?? [])
+                .map((label) => (typeof label === "string" ? label : label?.name))
+                .filter((name) => typeof name === "string"),
+            );
+
+            const hasTriggerLabel = labelSet.has(triggerLabel);
+            if (hasTriggerLabel) {
+              labelSet.delete(triggerLabel);
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: target.number,
+                  name: triggerLabel,
+                });
+              } catch (error) {
+                if (error?.status !== 404) {
+                  throw error;
+                }
+              }
+            }
+
+            if (!hasTriggerLabel) {
+              return;
+            }
+
             const issue = context.payload.issue;
             if (issue) {
               const title = issue.title ?? "";
               const body = issue.body ?? "";
               const haystack = `${title}\n${body}`.toLowerCase();
-              const hasMoltbookLabel = (issue.labels ?? []).some((label) =>
-                typeof label === "string" ? label === "r: moltbook" : label?.name === "r: moltbook",
-              );
-              const hasTestflightLabel = (issue.labels ?? []).some((label) =>
-                typeof label === "string"
-                  ? label === "r: testflight"
-                  : label?.name === "r: testflight",
-              );
-              const hasSecurityLabel = (issue.labels ?? []).some((label) =>
-                typeof label === "string" ? label === "security" : label?.name === "security",
-              );
+              const hasMoltbookLabel = labelSet.has("r: moltbook");
+              const hasTestflightLabel = labelSet.has("r: testflight");
+              const hasSecurityLabel = labelSet.has("security");
               if (title.toLowerCase().includes("security") && !hasSecurityLabel) {
                 await github.rest.issues.addLabels({
                   owner: context.repo.owner,
@@ -83,7 +108,7 @@ jobs:
                   issue_number: issue.number,
                   labels: ["security"],
                 });
-                return;
+                labelSet.add("security");
               }
               if (title.toLowerCase().includes("testflight") && !hasTestflightLabel) {
                 await github.rest.issues.addLabels({
@@ -92,7 +117,7 @@ jobs:
                   issue_number: issue.number,
                   labels: ["r: testflight"],
                 });
-                return;
+                labelSet.add("r: testflight");
               }
               if (haystack.includes("moltbook") && !hasMoltbookLabel) {
                 await github.rest.issues.addLabels({
@@ -101,24 +126,36 @@ jobs:
                   issue_number: issue.number,
                   labels: ["r: moltbook"],
                 });
+                labelSet.add("r: moltbook");
+              }
+            }
+
+            const pullRequest = context.payload.pull_request;
+            if (pullRequest) {
+              const labelCount = labelSet.size;
+              if (labelCount > 20) {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  body: "Closing this PR because it has more than 20 labels, which usually means the branch is too noisy. Please recreate the PR from a clean branch.",
+                });
+                await github.rest.issues.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pullRequest.number,
+                  state: "closed",
+                });
                 return;
               }
             }
 
-            const labelName = context.payload.label?.name;
-            if (!labelName) {
-              return;
-            }
-
-            const rule = rules.find((item) => item.label === labelName);
+            const rule = rules.find((item) => labelSet.has(item.label));
             if (!rule) {
               return;
             }
 
-            const issueNumber = context.payload.issue?.number ?? context.payload.pull_request?.number;
-            if (!issueNumber) {
-              return;
-            }
+            const issueNumber = target.number;
 
             await github.rest.issues.createComment({
               owner: context.repo.owner,

.github/workflows/ci.yml

@@ -84,6 +84,10 @@ jobs:
             esac
 
             case "$path" in
+              # Generated protocol models are already covered by protocol:check and
+              # should not force the full native macOS lane.
+              apps/macos/Sources/OpenClawProtocol/*|apps/shared/OpenClawKit/Sources/OpenClawProtocol/*)
+                ;;
               apps/macos/*|apps/ios/*|apps/shared/*|Swabble/*)
                 run_macos=true
                 ;;
@@ -121,7 +125,7 @@ jobs:
 
   # Build dist once for Node-relevant changes and share it with downstream jobs.
   build-artifacts:
-    needs: [docs-scope, changed-scope, code-analysis, check]
+    needs: [docs-scope, changed-scope, check]
     if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
@@ -171,7 +175,7 @@ jobs:
         run: pnpm release:check
 
   checks:
-    needs: [docs-scope, changed-scope, code-analysis, check]
+    needs: [docs-scope, changed-scope, check]
     if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:
@@ -196,9 +200,28 @@ jobs:
       - name: Setup Node environment
         uses: ./.github/actions/setup-node-env
 
+      - name: Configure vitest JSON reports
+        if: matrix.task == 'test' && matrix.runtime == 'node'
+        run: echo "OPENCLAW_VITEST_REPORT_DIR=$RUNNER_TEMP/vitest-reports" >> "$GITHUB_ENV"
+
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
+      - name: Summarize slowest tests
+        if: matrix.task == 'test' && matrix.runtime == 'node'
+        run: |
+          node scripts/vitest-slowest.mjs --dir "$OPENCLAW_VITEST_REPORT_DIR" --top 50 --out "$RUNNER_TEMP/vitest-slowest.md" > /dev/null
+          echo "Slowest test summary written to $RUNNER_TEMP/vitest-slowest.md"
+
+      - name: Upload vitest reports
+        if: matrix.task == 'test' && matrix.runtime == 'node'
+        uses: actions/upload-artifact@v4
+        with:
+          name: vitest-reports-${{ runner.os }}-${{ matrix.runtime }}
+          path: |
+            ${{ env.OPENCLAW_VITEST_REPORT_DIR }}
+            ${{ runner.temp }}/vitest-slowest.md
+
   # Types, lint, and format check.
   check:
     name: "check"
@@ -234,37 +257,6 @@ jobs:
       - name: Check docs
         run: pnpm check:docs
 
-  # Check for files that grew past LOC threshold in this PR (delta-only).
-  # On push events, all steps are skipped and the job passes (no-op).
-  # Heavy downstream jobs depend on this to fail fast on violations.
-  code-analysis:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    steps:
-      - name: Checkout
-        if: github.event_name == 'pull_request'
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          submodules: false
-
-      - name: Setup Python
-        if: github.event_name == 'pull_request'
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Fetch base branch
-        if: github.event_name == 'pull_request'
-        run: git fetch origin ${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}
-
-      - name: Check code file sizes
-        if: github.event_name == 'pull_request'
-        run: |
-          python scripts/analyze_code_files.py \
-            --compare-to origin/${{ github.base_ref }} \
-            --threshold 1000 \
-            --strict
-
   secrets:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
@@ -291,7 +283,7 @@ jobs:
           fi
 
   checks-windows:
-    needs: [docs-scope, changed-scope, build-artifacts, code-analysis, check]
+    needs: [docs-scope, changed-scope, build-artifacts, check]
     if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
     runs-on: blacksmith-4vcpu-windows-2025
     env:
@@ -391,15 +383,34 @@ 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: Configure vitest JSON reports
+        if: matrix.task == 'test'
+        run: echo "OPENCLAW_VITEST_REPORT_DIR=$RUNNER_TEMP/vitest-reports" >> "$GITHUB_ENV"
+
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
+      - name: Summarize slowest tests
+        if: matrix.task == 'test'
+        run: |
+          node scripts/vitest-slowest.mjs --dir "$OPENCLAW_VITEST_REPORT_DIR" --top 50 --out "$RUNNER_TEMP/vitest-slowest.md" > /dev/null
+          echo "Slowest test summary written to $RUNNER_TEMP/vitest-slowest.md"
+
+      - name: Upload vitest reports
+        if: matrix.task == 'test'
+        uses: actions/upload-artifact@v4
+        with:
+          name: vitest-reports-${{ runner.os }}-${{ matrix.runtime }}
+          path: |
+            ${{ env.OPENCLAW_VITEST_REPORT_DIR }}
+            ${{ runner.temp }}/vitest-slowest.md
+
   # Consolidated macOS job: runs TS tests + Swift lint/build/test sequentially
   # on a single runner. GitHub limits macOS concurrent jobs to 5 per org;
   # running 4 separate jobs per PR (as before) starved the queue. One job
   # per PR allows 5 PRs to run macOS checks simultaneously.
   macos:
-    needs: [docs-scope, changed-scope, code-analysis, check]
+    needs: [docs-scope, changed-scope, check]
     if: github.event_name == 'pull_request' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_macos == 'true'
     runs-on: macos-latest
     steps:
@@ -632,7 +643,7 @@ jobs:
           PY
 
   android:
-    needs: [docs-scope, changed-scope, code-analysis, check]
+    needs: [docs-scope, changed-scope, check]
     if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_android == 'true')
     runs-on: blacksmith-4vcpu-ubuntu-2404
     strategy:

.github/workflows/labeler.yml

@@ -5,6 +5,16 @@ on:
     types: [opened, synchronize, reopened]
   issues:
     types: [opened]
+  workflow_dispatch:
+    inputs:
+      max_prs:
+        description: "Maximum number of open PRs to process (0 = all)"
+        required: false
+        default: "200"
+      per_page:
+        description: "PRs per page (1-100)"
+        required: false
+        default: "50"
 
 permissions: {}
 
@@ -25,7 +35,96 @@ jobs:
           configuration-path: .github/labeler.yml
           repo-token: ${{ steps.app-token.outputs.token }}
           sync-labels: true
-      - name: Apply maintainer label for org members
+      - name: Apply PR size label
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const pullRequest = context.payload.pull_request;
+            if (!pullRequest) {
+              return;
+            }
+
+            const sizeLabels = ["size: XS", "size: S", "size: M", "size: L", "size: XL"];
+            const labelColor = "b76e79";
+
+            for (const label of sizeLabels) {
+              try {
+                await github.rest.issues.getLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: label,
+                });
+              } catch (error) {
+                if (error?.status !== 404) {
+                  throw error;
+                }
+                await github.rest.issues.createLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: label,
+                  color: labelColor,
+                });
+              }
+            }
+
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pullRequest.number,
+              per_page: 100,
+            });
+
+            const excludedLockfiles = new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
+            const totalChangedLines = files.reduce((total, file) => {
+              const path = file.filename ?? "";
+              if (path === "docs.acp.md" || path.startsWith("docs/") || excludedLockfiles.has(path)) {
+                return total;
+              }
+              return total + (file.additions ?? 0) + (file.deletions ?? 0);
+            }, 0);
+
+            let targetSizeLabel = "size: XL";
+            if (totalChangedLines < 50) {
+              targetSizeLabel = "size: XS";
+            } else if (totalChangedLines < 200) {
+              targetSizeLabel = "size: S";
+            } else if (totalChangedLines < 500) {
+              targetSizeLabel = "size: M";
+            } else if (totalChangedLines < 1000) {
+              targetSizeLabel = "size: L";
+            }
+
+            const currentLabels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pullRequest.number,
+              per_page: 100,
+            });
+
+            for (const label of currentLabels) {
+              const name = label.name ?? "";
+              if (!sizeLabels.includes(name)) {
+                continue;
+              }
+              if (name === targetSizeLabel) {
+                continue;
+              }
+              await github.rest.issues.removeLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: pullRequest.number,
+                name,
+              });
+            }
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pullRequest.number,
+              labels: [targetSizeLabel],
+            });
+      - name: Apply maintainer or trusted-contributor label
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           github-token: ${{ steps.app-token.outputs.token }}
@@ -35,6 +134,12 @@ jobs:
               return;
             }
 
+            const repo = `${context.repo.owner}/${context.repo.repo}`;
+            const trustedLabel = "trusted-contributor";
+            const experiencedLabel = "experienced-contributor";
+            const trustedThreshold = 4;
+            const experiencedThreshold = 10;
+
             let isMaintainer = false;
             try {
               const membership = await github.rest.teams.getMembershipForUserInOrg({
@@ -49,15 +154,288 @@ jobs:
               }
             }
 
-            if (!isMaintainer) {
+            if (isMaintainer) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.pull_request.number,
+                labels: ["maintainer"],
+              });
               return;
             }
 
-            await github.rest.issues.addLabels({
-              ...context.repo,
-              issue_number: context.payload.pull_request.number,
-              labels: ["maintainer"],
-            });
+            const mergedQuery = `repo:${repo} is:pr is:merged author:${login}`;
+            let mergedCount = 0;
+            try {
+              const merged = await github.rest.search.issuesAndPullRequests({
+                q: mergedQuery,
+                per_page: 1,
+              });
+              mergedCount = merged?.data?.total_count ?? 0;
+            } catch (error) {
+              if (error?.status !== 422) {
+                throw error;
+              }
+              core.warning(`Skipping merged search for ${login}; treating as 0.`);
+            }
+
+            if (mergedCount >= experiencedThreshold) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.pull_request.number,
+                labels: [experiencedLabel],
+              });
+              return;
+            }
+
+            if (mergedCount >= trustedThreshold) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.pull_request.number,
+                labels: [trustedLabel],
+              });
+            }
+
+  backfill-pr-labels:
+    if: github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+        id: app-token
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+      - name: Backfill PR labels
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const repoFull = `${owner}/${repo}`;
+            const inputs = context.payload.inputs ?? {};
+            const maxPrsInput = inputs.max_prs ?? "200";
+            const perPageInput = inputs.per_page ?? "50";
+            const parsedMaxPrs = Number.parseInt(maxPrsInput, 10);
+            const parsedPerPage = Number.parseInt(perPageInput, 10);
+            const maxPrs = Number.isFinite(parsedMaxPrs) ? parsedMaxPrs : 200;
+            const perPage = Number.isFinite(parsedPerPage) ? Math.min(100, Math.max(1, parsedPerPage)) : 50;
+            const processAll = maxPrs <= 0;
+            const maxCount = processAll ? Number.POSITIVE_INFINITY : Math.max(1, maxPrs);
+
+            const sizeLabels = ["size: XS", "size: S", "size: M", "size: L", "size: XL"];
+            const labelColor = "b76e79";
+            const trustedLabel = "trusted-contributor";
+            const experiencedLabel = "experienced-contributor";
+            const trustedThreshold = 4;
+            const experiencedThreshold = 10;
+
+            const contributorCache = new Map();
+
+            async function ensureSizeLabels() {
+              for (const label of sizeLabels) {
+                try {
+                  await github.rest.issues.getLabel({
+                    owner,
+                    repo,
+                    name: label,
+                  });
+                } catch (error) {
+                  if (error?.status !== 404) {
+                    throw error;
+                  }
+                  await github.rest.issues.createLabel({
+                    owner,
+                    repo,
+                    name: label,
+                    color: labelColor,
+                  });
+                }
+              }
+            }
+
+            async function resolveContributorLabel(login) {
+              if (contributorCache.has(login)) {
+                return contributorCache.get(login);
+              }
+
+              let isMaintainer = false;
+              try {
+                const membership = await github.rest.teams.getMembershipForUserInOrg({
+                  org: owner,
+                  team_slug: "maintainer",
+                  username: login,
+                });
+                isMaintainer = membership?.data?.state === "active";
+              } catch (error) {
+                if (error?.status !== 404) {
+                  throw error;
+                }
+              }
+
+              if (isMaintainer) {
+                contributorCache.set(login, "maintainer");
+                return "maintainer";
+              }
+
+              const mergedQuery = `repo:${repoFull} is:pr is:merged author:${login}`;
+              let mergedCount = 0;
+              try {
+                const merged = await github.rest.search.issuesAndPullRequests({
+                  q: mergedQuery,
+                  per_page: 1,
+                });
+                mergedCount = merged?.data?.total_count ?? 0;
+              } catch (error) {
+                if (error?.status !== 422) {
+                  throw error;
+                }
+                core.warning(`Skipping merged search for ${login}; treating as 0.`);
+              }
+
+              let label = null;
+              if (mergedCount >= experiencedThreshold) {
+                label = experiencedLabel;
+              } else if (mergedCount >= trustedThreshold) {
+                label = trustedLabel;
+              }
+
+              contributorCache.set(login, label);
+              return label;
+            }
+
+            async function applySizeLabel(pullRequest, currentLabels, labelNames) {
+              const files = await github.paginate(github.rest.pulls.listFiles, {
+                owner,
+                repo,
+                pull_number: pullRequest.number,
+                per_page: 100,
+              });
+
+              const excludedLockfiles = new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
+              const totalChangedLines = files.reduce((total, file) => {
+                const path = file.filename ?? "";
+                if (path === "docs.acp.md" || path.startsWith("docs/") || excludedLockfiles.has(path)) {
+                  return total;
+                }
+                return total + (file.additions ?? 0) + (file.deletions ?? 0);
+              }, 0);
+
+              let targetSizeLabel = "size: XL";
+              if (totalChangedLines < 50) {
+                targetSizeLabel = "size: XS";
+              } else if (totalChangedLines < 200) {
+                targetSizeLabel = "size: S";
+              } else if (totalChangedLines < 500) {
+                targetSizeLabel = "size: M";
+              } else if (totalChangedLines < 1000) {
+                targetSizeLabel = "size: L";
+              }
+
+              for (const label of currentLabels) {
+                const name = label.name ?? "";
+                if (!sizeLabels.includes(name)) {
+                  continue;
+                }
+                if (name === targetSizeLabel) {
+                  continue;
+                }
+                await github.rest.issues.removeLabel({
+                  owner,
+                  repo,
+                  issue_number: pullRequest.number,
+                  name,
+                });
+                labelNames.delete(name);
+              }
+
+              if (!labelNames.has(targetSizeLabel)) {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: pullRequest.number,
+                  labels: [targetSizeLabel],
+                });
+                labelNames.add(targetSizeLabel);
+              }
+            }
+
+            async function applyContributorLabel(pullRequest, labelNames) {
+              const login = pullRequest.user?.login;
+              if (!login) {
+                return;
+              }
+
+              const label = await resolveContributorLabel(login);
+              if (!label) {
+                return;
+              }
+
+              if (labelNames.has(label)) {
+                return;
+              }
+
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: pullRequest.number,
+                labels: [label],
+              });
+              labelNames.add(label);
+            }
+
+            await ensureSizeLabels();
+
+            let page = 1;
+            let processed = 0;
+
+            while (processed < maxCount) {
+              const remaining = maxCount - processed;
+              const pageSize = processAll ? perPage : Math.min(perPage, remaining);
+              const { data: pullRequests } = await github.rest.pulls.list({
+                owner,
+                repo,
+                state: "open",
+                per_page: pageSize,
+                page,
+              });
+
+              if (pullRequests.length === 0) {
+                break;
+              }
+
+              for (const pullRequest of pullRequests) {
+                if (!processAll && processed >= maxCount) {
+                  break;
+                }
+
+                const currentLabels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
+                  owner,
+                  repo,
+                  issue_number: pullRequest.number,
+                  per_page: 100,
+                });
+
+                const labelNames = new Set(
+                  currentLabels.map((label) => label.name).filter((name) => typeof name === "string"),
+                );
+
+                await applySizeLabel(pullRequest, currentLabels, labelNames);
+                await applyContributorLabel(pullRequest, labelNames);
+
+                processed += 1;
+              }
+
+              if (pullRequests.length < pageSize) {
+                break;
+              }
+
+              page += 1;
+            }
+
+            core.info(`Processed ${processed} pull requests.`);
 
   label-issues:
     permissions:
@@ -69,7 +447,7 @@ jobs:
         with:
           app-id: "2729701"
           private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - name: Apply maintainer label for org members
+      - name: Apply maintainer or trusted-contributor label
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           github-token: ${{ steps.app-token.outputs.token }}
@@ -79,6 +457,12 @@ jobs:
               return;
             }
 
+            const repo = `${context.repo.owner}/${context.repo.repo}`;
+            const trustedLabel = "trusted-contributor";
+            const experiencedLabel = "experienced-contributor";
+            const trustedThreshold = 4;
+            const experiencedThreshold = 10;
+
             let isMaintainer = false;
             try {
               const membership = await github.rest.teams.getMembershipForUserInOrg({
@@ -93,12 +477,43 @@ jobs:
               }
             }
 
-            if (!isMaintainer) {
+            if (isMaintainer) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.issue.number,
+                labels: ["maintainer"],
+              });
               return;
             }
 
-            await github.rest.issues.addLabels({
-              ...context.repo,
-              issue_number: context.payload.issue.number,
-              labels: ["maintainer"],
-            });
+            const mergedQuery = `repo:${repo} is:pr is:merged author:${login}`;
+            let mergedCount = 0;
+            try {
+              const merged = await github.rest.search.issuesAndPullRequests({
+                q: mergedQuery,
+                per_page: 1,
+              });
+              mergedCount = merged?.data?.total_count ?? 0;
+            } catch (error) {
+              if (error?.status !== 422) {
+                throw error;
+              }
+              core.warning(`Skipping merged search for ${login}; treating as 0.`);
+            }
+
+            if (mergedCount >= experiencedThreshold) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.issue.number,
+                labels: [experiencedLabel],
+              });
+              return;
+            }
+
+            if (mergedCount >= trustedThreshold) {
+              await github.rest.issues.addLabels({
+                ...context.repo,
+                issue_number: context.payload.issue.number,
+                labels: [trustedLabel],
+              });
+            }

.gitignore

@@ -69,9 +69,11 @@ apps/ios/*.mobileprovision
 
 # Local untracked files
 .local/
+docs/.local/
 IDENTITY.md
 USER.md
 .tgz
+.idea
 
 # local tooling
 .serena/

.markdownlint-cli2.jsonc

@@ -1,6 +1,6 @@
 {
   "globs": ["docs/**/*.md", "docs/**/*.mdx", "README.md"],
-  "ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**"],
+  "ignores": ["docs/zh-CN/**", "docs/.i18n/**", "docs/reference/templates/**", "**/.local/**"],
   "config": {
     "default": true,
 

.pi/prompts/landpr.md

@@ -11,8 +11,10 @@ Input
 Do (end-to-end)
 Goal: PR must end in GitHub state = MERGED (never CLOSED). Use `gh pr merge` with `--rebase` or `--squash`.
 
-1. Repo clean: `git status`.
-2. Identify PR meta (author + head branch):
+1. Assign PR to self:
+   - `gh pr edit <PR> --add-assignee @me`
+2. Repo clean: `git status`.
+3. Identify PR meta (author + head branch):
 
    ```sh
    gh pr view <PR> --json number,title,author,headRefName,baseRefName,headRepository --jq '{number,title,author:.author.login,head:.headRefName,base:.baseRefName,headRepo:.headRepository.nameWithOwner}'
@@ -21,50 +23,50 @@ Goal: PR must end in GitHub state = MERGED (never CLOSED). Use `gh pr merge` wit
    head_repo_url=$(gh pr view <PR> --json headRepository --jq .headRepository.url)
    ```
 
-3. Fast-forward base:
+4. Fast-forward base:
    - `git checkout main`
    - `git pull --ff-only`
-4. Create temp base branch from main:
+5. Create temp base branch from main:
    - `git checkout -b temp/landpr-<ts-or-pr>`
-5. Check out PR branch locally:
+6. Check out PR branch locally:
    - `gh pr checkout <PR>`
-6. Rebase PR branch onto temp base:
+7. Rebase PR branch onto temp base:
    - `git rebase temp/landpr-<ts-or-pr>`
    - Fix conflicts; keep history tidy.
-7. Fix + tests + changelog:
+8. Fix + tests + changelog:
    - Implement fixes + add/adjust tests
    - Update `CHANGELOG.md` and mention `#<PR>` + `@$contrib`
-8. Decide merge strategy:
+9. Decide merge strategy:
    - Rebase if we want to preserve commit history
    - Squash if we want a single clean commit
    - If unclear, ask
-9. Full gate (BEFORE commit):
-   - `pnpm lint && pnpm build && pnpm test`
-10. Commit via committer (include # + contributor in commit message):
+10. Full gate (BEFORE commit):
+    - `pnpm lint && pnpm build && pnpm test`
+11. Commit via committer (include # + contributor in commit message):
     - `committer "fix: <summary> (#<PR>) (thanks @$contrib)" CHANGELOG.md <changed files>`
     - `land_sha=$(git rev-parse HEAD)`
-11. Push updated PR branch (rebase => usually needs force):
+12. Push updated PR branch (rebase => usually needs force):
 
     ```sh
     git remote add prhead "$head_repo_url.git" 2>/dev/null || git remote set-url prhead "$head_repo_url.git"
     git push --force-with-lease prhead HEAD:$head
     ```
 
-12. Merge PR (must show MERGED on GitHub):
+13. Merge PR (must show MERGED on GitHub):
     - Rebase: `gh pr merge <PR> --rebase`
     - Squash: `gh pr merge <PR> --squash`
     - Never `gh pr close` (closing is wrong)
-13. Sync main:
+14. Sync main:
     - `git checkout main`
     - `git pull --ff-only`
-14. Comment on PR with what we did + SHAs + thanks:
+15. Comment on PR with what we did + SHAs + thanks:
 
     ```sh
     merge_sha=$(gh pr view <PR> --json mergeCommit --jq '.mergeCommit.oid')
     gh pr comment <PR> --body "Landed via temp rebase onto main.\n\n- Gate: pnpm lint && pnpm build && pnpm test\n- Land commit: $land_sha\n- Merge commit: $merge_sha\n\nThanks @$contrib!"
     ```
 
-15. Verify PR state == MERGED:
+16. Verify PR state == MERGED:
     - `gh pr view <PR> --json state --jq .state`
-16. Delete temp branch:
+17. Delete temp branch:
     - `git branch -D temp/landpr-<ts-or-pr>`

AGENTS.md

@@ -21,6 +21,7 @@
 
 - Docs are hosted on Mintlify (docs.openclaw.ai).
 - Internal doc links in `docs/**/*.md`: root-relative, no `.md`/`.mdx` (example: `[Config](/configuration)`).
+- When working with documentation, read the mintlify skill.
 - Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
 - Doc headings and anchors: avoid em dashes and apostrophes in headings because they break Mintlify anchor links.
 - When Peter asks for links, reply with full `https://docs.openclaw.ai/...` URLs (not root-relative).
@@ -60,6 +61,8 @@
 - Type-check/build: `pnpm build`
 - TypeScript checks: `pnpm tsgo`
 - Lint/format: `pnpm check`
+- Format check: `pnpm format` (oxfmt --check)
+- Format fix: `pnpm format:fix` (oxfmt --write)
 - Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`
 
 ## Coding Style & Naming Conventions
@@ -85,12 +88,13 @@
 - Do not set test workers above 16; tried already.
 - Live tests (real keys): `CLAWDBOT_LIVE_TEST=1 pnpm test:live` (OpenClaw-only) or `LIVE=1 pnpm test:live` (includes provider live tests). Docker: `pnpm test:docker:live-models`, `pnpm test:docker:live-gateway`. Onboarding Docker E2E: `pnpm test:docker:onboard`.
 - Full kit + what’s covered: `docs/testing.md`.
+- Changelog: user-facing changes only; no internal/meta notes (version alignment, appcast reminders, release process).
 - Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.
 - Mobile: before using a simulator, check for connected real devices (iOS + Android) and prefer them when available.
 
 ## Commit & Pull Request Guidelines
 
-**Full maintainer PR workflow:** `.agents/skills/PR_WORKFLOW.md` -- triage order, quality bar, rebase rules, commit/changelog conventions, co-contributor policy, and the 3-step skill pipeline (`review-pr` > `prepare-pr` > `merge-pr`).
+**Full maintainer PR workflow (optional):** If you want the repo's end-to-end maintainer workflow (triage order, quality bar, rebase rules, commit/changelog conventions, co-contributor policy, and the `review-pr` > `prepare-pr` > `merge-pr` pipeline), see `.agents/skills/PR_WORKFLOW.md`. Maintainers may use other workflows; when a maintainer specifies a workflow, follow that. If no workflow is specified, default to PR_WORKFLOW.
 
 - Create commits with `scripts/committer "<msg>" <file...>`; avoid manual `git add`/`git commit` so staging stays scoped.
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
@@ -133,6 +137,7 @@
 - SwiftUI state management (iOS/macOS): prefer the `Observation` framework (`@Observable`, `@Bindable`) over `ObservableObject`/`@StateObject`; don’t introduce new `ObservableObject` unless required for compatibility, and migrate existing usages when touching related code.
 - Connection providers: when adding a new connection, update every UI surface and docs (macOS app, web UI, mobile if applicable, onboarding/overview docs) and add matching status + configuration forms so provider lists and settings stay in sync.
 - Version locations: `package.json` (CLI), `apps/android/app/build.gradle.kts` (versionName/versionCode), `apps/ios/Sources/Info.plist` + `apps/ios/Tests/Info.plist` (CFBundleShortVersionString/CFBundleVersion), `apps/macos/Sources/OpenClaw/Resources/Info.plist` (CFBundleShortVersionString/CFBundleVersion), `docs/install/updating.md` (pinned npm version), `docs/platforms/mac/release.md` (APP_VERSION/APP_BUILD examples), Peekaboo Xcode projects/Info.plists (MARKETING_VERSION/CURRENT_PROJECT_VERSION).
+- "Bump version everywhere" means all version locations above **except** `appcast.xml` (only touch appcast when cutting a new macOS Sparkle release).
 - **Restart apps:** “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
 - **Device checks:** before testing, verify connected real devices (iOS/Android) before reaching for simulators/emulators.
 - iOS Team ID lookup: `security find-identity -p codesigning -v` → use Apple Development (…) TEAMID. Fallback: `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.

CHANGELOG.md

@@ -2,6 +2,117 @@
 
 Docs: https://docs.openclaw.ai
 
+## 2026.2.13 (Unreleased)
+
+### Fixes
+
+- Security/Audit: distinguish external webhooks (`hooks.enabled`) from internal hooks (`hooks.internal.enabled`) in attack-surface summaries to avoid false exposure signals when only internal hooks are enabled. (#13474) Thanks @mcaxtr.
+- Auto-reply/Threading: auto-inject implicit reply threading so `replyToMode` works without requiring model-emitted `[[reply_to_current]]`, while preserving `replyToMode: "off"` behavior for implicit Slack replies and keeping block-streaming chunk coalescing stable under `replyToMode: "first"`. (#14976) Thanks @Diaspar4u.
+- Sandbox: pass configured `sandbox.docker.env` variables to sandbox containers at `docker create` time. (#15138) Thanks @stevebot-alive.
+- Onboarding/CLI: restore terminal state without resuming paused `stdin`, so onboarding exits cleanly after choosing Web UI and the installer returns instead of appearing stuck.
+- macOS Voice Wake: fix a crash in trigger trimming for CJK/Unicode transcripts by matching and slicing on original-string ranges instead of transformed-string indices. (#11052) Thanks @Flash-LHR.
+- Heartbeat: prevent scheduler silent-death races during runner reloads, preserve retry cooldown backoff under wake bursts, and prioritize user/action wake causes over interval/retry reasons when coalescing. (#15108) Thanks @joeykrug.
+- Outbound targets: fail closed for WhatsApp/Twitch/Google Chat fallback paths so invalid or missing targets are dropped instead of rerouted, and align resolver hints with strict target requirements. (#13578) Thanks @mcaxtr.
+- Exec/Allowlist: allow multiline heredoc bodies (`<<`, `<<-`) while keeping multiline non-heredoc shell commands blocked, so exec approval parsing permits heredoc input safely without allowing general newline command chaining. (#13811) Thanks @mcaxtr.
+- Docs/Mermaid: remove hardcoded Mermaid init theme blocks from four docs diagrams so dark mode inherits readable theme defaults. (#15157) Thanks @heytulsiprasad.
+- Outbound/Threading: pass `replyTo` and `threadId` from `message send` tool actions through the core outbound send path to channel adapters, preserving thread/reply routing. (#14948) Thanks @mcaxtr.
+- Sessions/Agents: pass `agentId` when resolving existing transcript paths in reply runs so non-default agents and heartbeat/chat handlers no longer fail with `Session file path must be within sessions directory`. (#15141) Thanks @Goldenmonstew.
+
+## 2026.2.12
+
+### Changes
+
+- CLI/Plugins: add `openclaw plugins uninstall <id>` with `--dry-run`, `--force`, and `--keep-files` options, including safe uninstall path handling and plugin uninstall docs. (#5985) Thanks @JustasMonkev.
+- CLI: add `openclaw logs --local-time` to display log timestamps in local timezone. (#13818) Thanks @xialonglee.
+- Telegram: render blockquotes as native `<blockquote>` tags instead of stripping them. (#14608)
+- Telegram: expose `/compact` in the native command menu. (#10352) Thanks @akramcodez.
+- Discord: add role-based allowlists and role-based agent routing. (#10650) Thanks @Minidoracat.
+- Config: avoid redacting `maxTokens`-like fields during config snapshot redaction, preventing round-trip validation failures in `/config`. (#14006) Thanks @constansino.
+
+### Breaking
+
+- Hooks: `POST /hooks/agent` now rejects payload `sessionKey` overrides by default. To keep fixed hook context, set `hooks.defaultSessionKey` (recommended with `hooks.allowedSessionKeyPrefixes: ["hook:"]`). If you need legacy behavior, explicitly set `hooks.allowRequestSessionKey: true`. Thanks @alpernae for reporting.
+
+### Fixes
+
+- Gateway/OpenResponses: harden URL-based `input_file`/`input_image` handling with explicit SSRF deny policy, hostname allowlists (`files.urlAllowlist` / `images.urlAllowlist`), per-request URL input caps (`maxUrlParts`), blocked-fetch audit logging, and regression coverage/docs updates.
+- Security: fix unauthenticated Nostr profile API remote config tampering. (#13719) Thanks @coygeek.
+- Security: remove bundled soul-evil hook. (#14757) Thanks @Imccccc.
+- Security/Audit: add hook session-routing hardening checks (`hooks.defaultSessionKey`, `hooks.allowRequestSessionKey`, and prefix allowlists), and warn when HTTP API endpoints allow explicit session-key routing.
+- Security/Sandbox: confine mirrored skill sync destinations to the sandbox `skills/` root and stop using frontmatter-controlled skill names as filesystem destination paths. Thanks @1seal.
+- Security/Web tools: treat browser/web content as untrusted by default (wrapped outputs for browser snapshot/tabs/console and structured external-content metadata for web tools), and strip `toolResult.details` from model-facing transcript/compaction inputs to reduce prompt-injection replay risk.
+- Security/Hooks: harden webhook and device token verification with shared constant-time secret comparison, and add per-client auth-failure throttling for hook endpoints (`429` + `Retry-After`). Thanks @akhmittra.
+- Security/Browser: require auth for loopback browser control HTTP routes, auto-generate `gateway.auth.token` when browser control starts without auth, and add a security-audit check for unauthenticated browser control. Thanks @tcusolle.
+- Sessions/Gateway: harden transcript path resolution and reject unsafe session IDs/file paths so session operations stay within agent sessions directories. Thanks @akhmittra.
+- Sessions: preserve `verboseLevel`, `thinkingLevel`/`reasoningLevel`, and `ttsAuto` overrides across `/new` and `/reset` session resets. (#10787) Thanks @mcaxtr.
+- Gateway: raise WS payload/buffer limits so 5,000,000-byte image attachments work reliably. (#14486) Thanks @0xRaini.
+- Logging/CLI: use local timezone timestamps for console prefixing, and include `±HH:MM` offsets when using `openclaw logs --local-time` to avoid ambiguity. (#14771) Thanks @0xRaini.
+- Gateway: drain active turns before restart to prevent message loss. (#13931) Thanks @0xRaini.
+- Gateway: auto-generate auth token during install to prevent launchd restart loops. (#13813) Thanks @cathrynlavery.
+- Gateway: prevent `undefined`/missing token in auth config. (#13809) Thanks @asklee-klawd.
+- Gateway: handle async `EPIPE` on stdout/stderr during shutdown. (#13414) Thanks @keshav55.
+- Gateway/Control UI: resolve missing dashboard assets when `openclaw` is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.
+- Cron: use requested `agentId` for isolated job auth resolution. (#13983) Thanks @0xRaini.
+- Cron: prevent cron jobs from skipping execution when `nextRunAtMs` advances. (#14068) Thanks @WalterSumbon.
+- Cron: pass `agentId` to `runHeartbeatOnce` for main-session jobs. (#14140) Thanks @ishikawa-pro.
+- Cron: re-arm timers when `onTimer` fires while a job is still executing. (#14233) Thanks @tomron87.
+- Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.
+- Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.
+- Cron: prevent one-shot `at` jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.
+- Heartbeat: prevent scheduler stalls on unexpected run errors and avoid immediate rerun loops after `requests-in-flight` skips. (#14901) Thanks @joeykrug.
+- Cron: honor stored session model overrides for isolated-agent runs while preserving `hooks.gmail.model` precedence for Gmail hook sessions. (#14983) Thanks @shtse8.
+- Logging/Browser: fall back to `os.tmpdir()/openclaw` for default log, browser trace, and browser download temp paths when `/tmp/openclaw` is unavailable.
+- WhatsApp: convert Markdown bold/strikethrough to WhatsApp formatting. (#14285) Thanks @Raikan10.
+- WhatsApp: allow media-only sends and normalize leading blank payloads. (#14408) Thanks @karimnaguib.
+- WhatsApp: default MIME type for voice messages when Baileys omits it. (#14444) Thanks @mcaxtr.
+- Telegram: handle no-text message in model picker editMessageText. (#14397) Thanks @0xRaini.
+- Telegram: surface REACTION_INVALID as non-fatal warning. (#14340) Thanks @0xRaini.
+- BlueBubbles: fix webhook auth bypass via loopback proxy trust. (#13787) Thanks @coygeek.
+- Slack: change default replyToMode from "off" to "all". (#14364) Thanks @nm-de.
+- Slack: detect control commands when channel messages start with bot mention prefixes (for example, `@Bot /new`). (#14142) Thanks @beefiker.
+- Slack: include thread reply metadata in inbound message footer context (`thread_ts`, `parent_user_id`) while keeping top-level `thread_ts == ts` events unthreaded. (#14625) Thanks @bennewton999.
+- Signal: enforce E.164 validation for the Signal bot account prompt so mistyped numbers are caught early. (#15063) Thanks @Duartemartins.
+- Discord: process DM reactions instead of silently dropping them. (#10418) Thanks @mcaxtr.
+- Discord: treat Administrator as full permissions in channel permission checks. Thanks @thewilloftheshadow.
+- Discord: respect replyToMode in threads. (#11062) Thanks @cordx56.
+- Browser: add Chrome launch flag `--disable-blink-features=AutomationControlled` to reduce `navigator.webdriver` automation detection issues on reCAPTCHA-protected sites. (#10735) Thanks @Milofax.
+- Heartbeat: filter noise-only system events so scheduled reminder notifications do not fire when cron runs carry only heartbeat markers. (#13317) Thanks @pvtclawn.
+- Signal: render mention placeholders as `@uuid`/`@phone` so mention gating and Clawdbot targeting work. (#2013) Thanks @alexgleason.
+- Discord: omit empty content fields for media-only messages while preserving caption whitespace. (#9507) Thanks @leszekszpunar.
+- Onboarding/Providers: add Z.AI endpoint-specific auth choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) and expand default Z.AI model wiring. (#13456) Thanks @tomsun28.
+- Onboarding/Providers: update MiniMax API default/recommended models from M2.1 to M2.5, add M2.5/M2.5-Lightning model entries, and include `minimax-m2.5` in modern model filtering. (#14865) Thanks @adao-max.
+- Ollama: use configured `models.providers.ollama.baseUrl` for model discovery and normalize `/v1` endpoints to the native Ollama API root. (#14131) Thanks @shtse8.
+- Voice Call: pass Twilio stream auth token via `<Parameter>` instead of query string. (#14029) Thanks @mcwigglesmcgee.
+- Feishu: pass `Buffer` directly to the Feishu SDK upload APIs instead of `Readable.from(...)` to avoid form-data upload failures. (#10345) Thanks @youngerstyle.
+- Feishu: trigger mention-gated group handling only when the bot itself is mentioned (not just any mention). (#11088) Thanks @openperf.
+- Feishu: probe status uses the resolved account context for multi-account credential checks. (#11233) Thanks @onevcat.
+- Feishu: add streaming card replies via Card Kit API and preserve `renderMode=auto` fallback behavior for plain-text responses. (#10379) Thanks @xzq-xu.
+- Feishu DocX: preserve top-level converted block order using `firstLevelBlockIds` when writing/appending documents. (#13994) Thanks @Cynosure159.
+- Feishu plugin packaging: remove `workspace:*` `openclaw` dependency from `extensions/feishu` and sync lockfile for install compatibility. (#14423) Thanks @jackcooper2015.
+- CLI/Wizard: exit with code 1 when `configure`, `agents add`, or interactive `onboard` wizards are canceled, so `set -e` automation stops correctly. (#14156) Thanks @0xRaini.
+- Media: strip `MEDIA:` lines with local paths instead of leaking as visible text. (#14399) Thanks @0xRaini.
+- Config/Cron: exclude `maxTokens` from config redaction and honor `deleteAfterRun` on skipped cron jobs. (#13342) Thanks @niceysam.
+- Config: ignore `meta` field changes in config file watcher. (#13460) Thanks @brandonwise.
+- Cron: use requested `agentId` for isolated job auth resolution. (#13983) Thanks @0xRaini.
+- Cron: pass `agentId` to `runHeartbeatOnce` for main-session jobs. (#14140) Thanks @ishikawa-pro.
+- Cron: prevent cron jobs from skipping execution when `nextRunAtMs` advances. (#14068) Thanks @WalterSumbon.
+- Cron: re-arm timers when `onTimer` fires while a job is still executing. (#14233) Thanks @tomron87.
+- Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.
+- Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.
+- Cron: prevent one-shot `at` jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.
+- Daemon: suppress `EPIPE` error when restarting LaunchAgent. (#14343) Thanks @0xRaini.
+- Antigravity: add opus 4.6 forward-compat model and bypass thinking signature sanitization. (#14218) Thanks @jg-noncelogic.
+- Agents: prevent file descriptor leaks in child process cleanup. (#13565) Thanks @KyleChen26.
+- Agents: prevent double compaction caused by cache TTL bypassing guard. (#13514) Thanks @taw0002.
+- Agents: use last API call's cache tokens for context display instead of accumulated sum. (#13805) Thanks @akari-musubi.
+- Agents: keep followup-runner session `totalTokens` aligned with post-compaction context by using last-call usage and shared token-accounting logic. (#14979) Thanks @shtse8.
+- Hooks/Plugins: wire 9 previously unwired plugin lifecycle hooks into core runtime paths (session, compaction, gateway, and outbound message hooks). (#14882) Thanks @shtse8.
+- Hooks/Tools: dispatch `before_tool_call` and `after_tool_call` hooks from both tool execution paths with rebased conflict fixes. (#15012) Thanks @Patrick-Barletta, @Takhoffman.
+- Discord: allow channel-edit to archive/lock threads and set auto-archive duration. (#5542) Thanks @stumct.
+- Discord tests: use a partial @buape/carbon mock in slash command coverage. (#13262) Thanks @arosstale.
+- Tests: update thread ID handling in Slack message collection tests. (#14108) Thanks @swizzmagik.
+- Update/Daemon: fix post-update restart compatibility by generating `dist/cli/daemon-cli.js` with alias-aware exports from hashed daemon bundles, preventing `registerDaemonCli` import failures during `openclaw update`.
+
 ## 2026.2.9
 
 ### Added
@@ -10,21 +121,26 @@ Docs: https://docs.openclaw.ai
 - Docker: add ClawDock shell helpers for Docker workflows. (#12817) Thanks @Olshansk.
 - iOS: alpha node app + setup-code onboarding. (#11756) Thanks @mbelinky.
 - Channels: comprehensive BlueBubbles and channel cleanup. (#11093) Thanks @tyler6204.
+- Channels: IRC first-class channel support. (#11482) Thanks @vignesh07.
 - Plugins: device pairing + phone control plugins (Telegram `/pair`, iOS/Android node controls). (#11755) Thanks @mbelinky.
 - Tools: add Grok (xAI) as a `web_search` provider. (#12419) Thanks @tmchow.
 - Gateway: add agent management RPC methods for the web UI (`agents.create`, `agents.update`, `agents.delete`). (#11045) Thanks @advaitpaliwal.
+- Gateway: stream thinking events to WS clients and broadcast tool events independent of verbose level. (#10568) Thanks @nk1tz.
 - Web UI: show a Compaction divider in chat history. (#11341) Thanks @Takhoffman.
 - Agents: include runtime shell in agent envelopes. (#1835) Thanks @Takhoffman.
 - Agents: auto-select `zai/glm-4.6v` for image understanding when ZAI is primary provider. (#10267) Thanks @liuy.
 - Paths: add `OPENCLAW_HOME` for overriding the home directory used by internal path resolution. (#12091) Thanks @sebslight.
 - Onboarding: add Custom Provider flow for OpenAI and Anthropic-compatible endpoints. (#11106) Thanks @MackDing.
+- Hooks: route webhook agent runs to specific `agentId`s, add `hooks.allowedAgentIds` controls, and fall back to default agent when unknown IDs are provided. (#13672) Thanks @BillChirico.
 
 ### Fixes
 
+- Cron: prevent one-shot `at` jobs from re-firing on gateway restart when previously skipped or errored. (#13845)
 - Discord: add exec approval cleanup option to delete DMs after approval/denial/timeout. (#13205) Thanks @thewilloftheshadow.
 - Sessions: prune stale entries, cap session store size, rotate large stores, accept duration/size thresholds, default to warn-only maintenance, and prune cron run sessions after retention windows. (#13083) Thanks @skyfallsin, @Glucksberg, @gumadeiras.
 - CI: Implement pipeline and workflow order. Thanks @quotentiroler.
 - WhatsApp: preserve original filenames for inbound documents. (#12691) Thanks @akramcodez.
+- Feishu: enforce DM `dmPolicy`/pairing gating and sender allow checks for inbound DMs. (#14876) Thanks @coygeek.
 - Telegram: harden quote parsing; preserve quote context; avoid QUOTE_TEXT_INVALID; avoid nested reply quote misclassification. (#12156) Thanks @rybnikov.
 - Telegram: recover proactive sends when stale topic thread IDs are used by retrying without `message_thread_id`. (#11620)
 - Discord: auto-create forum/media thread posts on send, with chunked follow-up replies and media handling for forum sends. (#12380) Thanks @magendary, @thewilloftheshadow.
@@ -32,11 +148,16 @@ Docs: https://docs.openclaw.ai
 - Telegram: render markdown spoilers with `<tg-spoiler>` HTML tags. (#11543) Thanks @ezhikkk.
 - Telegram: truncate command registration to 100 entries to avoid `BOT_COMMANDS_TOO_MUCH` failures on startup. (#12356) Thanks @arosstale.
 - Telegram: match DM `allowFrom` against sender user id (fallback to chat id) and clarify pairing logs. (#12779) Thanks @liuxiaopai-ai.
+- Pairing/Telegram: include the actual pairing code in approve commands, route Telegram pairing replies through the shared pairing message builder, and add regression checks to prevent `<code>` placeholder drift.
 - Onboarding: QuickStart now auto-installs shell completion (prompt only in Manual).
+- Onboarding/Providers: add LiteLLM provider onboarding and preserve custom LiteLLM proxy base URLs while enforcing API-key auth mode. (#12823) Thanks @ryan-crabbe.
 - Docker: make `docker-setup.sh` compatible with macOS Bash 3.2 and empty extra mounts. (#9441) Thanks @mateusz-michalik.
 - Auth: strip embedded line breaks from pasted API keys and tokens before storing/resolving credentials.
 - Agents: strip reasoning tags and downgraded tool markers from messaging tool and streaming output to prevent leakage. (#11053, #13453) Thanks @liebertar, @meaadore1221-afk, @gumadeiras.
+- Browser: prevent stuck `act:evaluate` from wedging the browser tool, and make cancellation stop waiting promptly. (#13498) Thanks @onutc.
+- Security/Gateway: default-deny missing connect `scopes` (no implicit `operator.admin`).
 - Web UI: make chat refresh smoothly scroll to the latest messages and suppress new-messages badge flash during manual refresh.
+- Web UI: coerce Form Editor values to schema types before `config.set` and `config.apply`, preventing numeric and boolean fields from being serialized as strings. (#13468) Thanks @mcaxtr.
 - Tools/web_search: include provider-specific settings in the web search cache key, and pass `inlineCitations` for Grok. (#12419) Thanks @tmchow.
 - Tools/web_search: fix Grok response parsing for xAI Responses API output blocks. (#13049) Thanks @ereid7.
 - Tools/web_search: normalize direct Perplexity model IDs while keeping OpenRouter model IDs unchanged. (#12795) Thanks @cdorsey.
@@ -48,11 +169,13 @@ Docs: https://docs.openclaw.ai
 - Gateway: fix multi-agent sessions.usage discovery. (#11523) Thanks @Takhoffman.
 - Agents: recover from context overflow caused by oversized tool results (pre-emptive capping + fallback truncation). (#11579) Thanks @tyler6204.
 - Subagents/compaction: stabilize announce timing and preserve compaction metrics across retries. (#11664) Thanks @tyler6204.
+- Subagents: report timeout-aborted runs as timed out instead of completed successfully in parent-session announcements. (#13996) Thanks @dario-github.
 - Cron: share isolated announce flow and harden scheduling/delivery reliability. (#11641) Thanks @tyler6204.
 - Cron tool: recover flat params when LLM omits the `job` wrapper for add requests. (#12124) Thanks @tyler6204.
 - Gateway/CLI: when `gateway.bind=lan`, use a LAN IP for probe URLs and Control UI links. (#11448) Thanks @AnonO6.
 - CLI: make `openclaw plugins list` output scannable by hoisting source roots and shortening bundled/global/workspace plugin paths.
 - Hooks: fix bundled hooks broken since 2026.2.2 (tsdown migration). (#9295) Thanks @patrickshao.
+- Security/Plugins: install plugin and hook dependencies with `--ignore-scripts` to prevent lifecycle script execution.
 - Routing: refresh bindings per message by loading config at route resolution so binding changes apply without restart. (#11372) Thanks @juanpablodlc.
 - Exec approvals: render forwarded commands in monospace for safer approval scanning. (#11937) Thanks @sebslight.
 - Config: clamp `maxTokens` to `contextWindow` to prevent invalid model configs. (#5516) Thanks @lailoo.
@@ -66,6 +189,8 @@ Docs: https://docs.openclaw.ai
 - Memory/QMD: run boot refresh in background by default, add configurable QMD maintenance timeouts, retry QMD after fallback failures, and scope QMD queries to OpenClaw-managed collections. (#9690, #9705, #10042) Thanks @vignesh07.
 - Memory/QMD: initialize QMD backend on gateway startup so background update timers restart after process reloads. (#10797) Thanks @vignesh07.
 - Config/Memory: auto-migrate legacy top-level `memorySearch` settings into `agents.defaults.memorySearch`. (#11278, #9143) Thanks @vignesh07.
+- Memory/QMD: treat plain-text `No results found` output from QMD as an empty result instead of throwing invalid JSON errors. (#9824)
+- Memory/QMD: add `memory.qmd.searchMode` to choose `query`, `search`, or `vsearch` recall mode. (#9967, #10084)
 - Media understanding: recognize `.caf` audio attachments for transcription. (#10982) Thanks @succ985.
 - State dir: honor `OPENCLAW_STATE_DIR` for default device identity and canvas storage paths. (#4824) Thanks @kossoy.
 
@@ -79,6 +204,7 @@ Docs: https://docs.openclaw.ai
 - 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.
+- Web UI: add RTL auto-direction support for Hebrew/Arabic text in chat composer and rendered messages. (#11498) Thanks @dirbalak.
 - 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.

appcast.xml

@@ -2,6 +2,102 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>OpenClaw</title>
+        <item>
+            <title>2026.2.12</title>
+            <pubDate>Fri, 13 Feb 2026 03:17:54 +0100</pubDate>
+            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
+            <sparkle:version>9500</sparkle:version>
+            <sparkle:shortVersionString>2026.2.12</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>OpenClaw 2026.2.12</h2>
+<h3>Changes</h3>
+<ul>
+<li>CLI: add <code>openclaw logs --local-time</code> to display log timestamps in local timezone. (#13818) Thanks @xialonglee.</li>
+<li>Telegram: render blockquotes as native <code><blockquote></code> tags instead of stripping them. (#14608)</li>
+<li>Config: avoid redacting <code>maxTokens</code>-like fields during config snapshot redaction, preventing round-trip validation failures in <code>/config</code>. (#14006) Thanks @constansino.</li>
+</ul>
+<h3>Breaking</h3>
+<ul>
+<li>Hooks: <code>POST /hooks/agent</code> now rejects payload <code>sessionKey</code> overrides by default. To keep fixed hook context, set <code>hooks.defaultSessionKey</code> (recommended with <code>hooks.allowedSessionKeyPrefixes: ["hook:"]</code>). If you need legacy behavior, explicitly set <code>hooks.allowRequestSessionKey: true</code>. Thanks @alpernae for reporting.</li>
+</ul>
+<h3>Fixes</h3>
+<ul>
+<li>Gateway/OpenResponses: harden URL-based <code>input_file</code>/<code>input_image</code> handling with explicit SSRF deny policy, hostname allowlists (<code>files.urlAllowlist</code> / <code>images.urlAllowlist</code>), per-request URL input caps (<code>maxUrlParts</code>), blocked-fetch audit logging, and regression coverage/docs updates.</li>
+<li>Security: fix unauthenticated Nostr profile API remote config tampering. (#13719) Thanks @coygeek.</li>
+<li>Security: remove bundled soul-evil hook. (#14757) Thanks @Imccccc.</li>
+<li>Security/Audit: add hook session-routing hardening checks (<code>hooks.defaultSessionKey</code>, <code>hooks.allowRequestSessionKey</code>, and prefix allowlists), and warn when HTTP API endpoints allow explicit session-key routing.</li>
+<li>Security/Sandbox: confine mirrored skill sync destinations to the sandbox <code>skills/</code> root and stop using frontmatter-controlled skill names as filesystem destination paths. Thanks @1seal.</li>
+<li>Security/Web tools: treat browser/web content as untrusted by default (wrapped outputs for browser snapshot/tabs/console and structured external-content metadata for web tools), and strip <code>toolResult.details</code> from model-facing transcript/compaction inputs to reduce prompt-injection replay risk.</li>
+<li>Security/Hooks: harden webhook and device token verification with shared constant-time secret comparison, and add per-client auth-failure throttling for hook endpoints (<code>429</code> + <code>Retry-After</code>). Thanks @akhmittra.</li>
+<li>Security/Browser: require auth for loopback browser control HTTP routes, auto-generate <code>gateway.auth.token</code> when browser control starts without auth, and add a security-audit check for unauthenticated browser control. Thanks @tcusolle.</li>
+<li>Sessions/Gateway: harden transcript path resolution and reject unsafe session IDs/file paths so session operations stay within agent sessions directories. Thanks @akhmittra.</li>
+<li>Gateway: raise WS payload/buffer limits so 5,000,000-byte image attachments work reliably. (#14486) Thanks @0xRaini.</li>
+<li>Logging/CLI: use local timezone timestamps for console prefixing, and include <code>±HH:MM</code> offsets when using <code>openclaw logs --local-time</code> to avoid ambiguity. (#14771) Thanks @0xRaini.</li>
+<li>Gateway: drain active turns before restart to prevent message loss. (#13931) Thanks @0xRaini.</li>
+<li>Gateway: auto-generate auth token during install to prevent launchd restart loops. (#13813) Thanks @cathrynlavery.</li>
+<li>Gateway: prevent <code>undefined</code>/missing token in auth config. (#13809) Thanks @asklee-klawd.</li>
+<li>Gateway: handle async <code>EPIPE</code> on stdout/stderr during shutdown. (#13414) Thanks @keshav55.</li>
+<li>Gateway/Control UI: resolve missing dashboard assets when <code>openclaw</code> is installed globally via symlink-based Node managers (nvm/fnm/n/Homebrew). (#14919) Thanks @aynorica.</li>
+<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
+<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
+<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
+<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
+<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
+<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
+<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
+<li>Heartbeat: prevent scheduler stalls on unexpected run errors and avoid immediate rerun loops after <code>requests-in-flight</code> skips. (#14901) Thanks @joeykrug.</li>
+<li>Cron: honor stored session model overrides for isolated-agent runs while preserving <code>hooks.gmail.model</code> precedence for Gmail hook sessions. (#14983) Thanks @shtse8.</li>
+<li>Logging/Browser: fall back to <code>os.tmpdir()/openclaw</code> for default log, browser trace, and browser download temp paths when <code>/tmp/openclaw</code> is unavailable.</li>
+<li>WhatsApp: convert Markdown bold/strikethrough to WhatsApp formatting. (#14285) Thanks @Raikan10.</li>
+<li>WhatsApp: allow media-only sends and normalize leading blank payloads. (#14408) Thanks @karimnaguib.</li>
+<li>WhatsApp: default MIME type for voice messages when Baileys omits it. (#14444) Thanks @mcaxtr.</li>
+<li>Telegram: handle no-text message in model picker editMessageText. (#14397) Thanks @0xRaini.</li>
+<li>Telegram: surface REACTION_INVALID as non-fatal warning. (#14340) Thanks @0xRaini.</li>
+<li>BlueBubbles: fix webhook auth bypass via loopback proxy trust. (#13787) Thanks @coygeek.</li>
+<li>Slack: change default replyToMode from "off" to "all". (#14364) Thanks @nm-de.</li>
+<li>Slack: detect control commands when channel messages start with bot mention prefixes (for example, <code>@Bot /new</code>). (#14142) Thanks @beefiker.</li>
+<li>Signal: enforce E.164 validation for the Signal bot account prompt so mistyped numbers are caught early. (#15063) Thanks @Duartemartins.</li>
+<li>Discord: process DM reactions instead of silently dropping them. (#10418) Thanks @mcaxtr.</li>
+<li>Discord: respect replyToMode in threads. (#11062) Thanks @cordx56.</li>
+<li>Heartbeat: filter noise-only system events so scheduled reminder notifications do not fire when cron runs carry only heartbeat markers. (#13317) Thanks @pvtclawn.</li>
+<li>Signal: render mention placeholders as <code>@uuid</code>/<code>@phone</code> so mention gating and Clawdbot targeting work. (#2013) Thanks @alexgleason.</li>
+<li>Discord: omit empty content fields for media-only messages while preserving caption whitespace. (#9507) Thanks @leszekszpunar.</li>
+<li>Onboarding/Providers: add Z.AI endpoint-specific auth choices (<code>zai-coding-global</code>, <code>zai-coding-cn</code>, <code>zai-global</code>, <code>zai-cn</code>) and expand default Z.AI model wiring. (#13456) Thanks @tomsun28.</li>
+<li>Onboarding/Providers: update MiniMax API default/recommended models from M2.1 to M2.5, add M2.5/M2.5-Lightning model entries, and include <code>minimax-m2.5</code> in modern model filtering. (#14865) Thanks @adao-max.</li>
+<li>Ollama: use configured <code>models.providers.ollama.baseUrl</code> for model discovery and normalize <code>/v1</code> endpoints to the native Ollama API root. (#14131) Thanks @shtse8.</li>
+<li>Voice Call: pass Twilio stream auth token via <code><Parameter></code> instead of query string. (#14029) Thanks @mcwigglesmcgee.</li>
+<li>Feishu: pass <code>Buffer</code> directly to the Feishu SDK upload APIs instead of <code>Readable.from(...)</code> to avoid form-data upload failures. (#10345) Thanks @youngerstyle.</li>
+<li>Feishu: trigger mention-gated group handling only when the bot itself is mentioned (not just any mention). (#11088) Thanks @openperf.</li>
+<li>Feishu: probe status uses the resolved account context for multi-account credential checks. (#11233) Thanks @onevcat.</li>
+<li>Feishu DocX: preserve top-level converted block order using <code>firstLevelBlockIds</code> when writing/appending documents. (#13994) Thanks @Cynosure159.</li>
+<li>Feishu plugin packaging: remove <code>workspace:*</code> <code>openclaw</code> dependency from <code>extensions/feishu</code> and sync lockfile for install compatibility. (#14423) Thanks @jackcooper2015.</li>
+<li>CLI/Wizard: exit with code 1 when <code>configure</code>, <code>agents add</code>, or interactive <code>onboard</code> wizards are canceled, so <code>set -e</code> automation stops correctly. (#14156) Thanks @0xRaini.</li>
+<li>Media: strip <code>MEDIA:</code> lines with local paths instead of leaking as visible text. (#14399) Thanks @0xRaini.</li>
+<li>Config/Cron: exclude <code>maxTokens</code> from config redaction and honor <code>deleteAfterRun</code> on skipped cron jobs. (#13342) Thanks @niceysam.</li>
+<li>Config: ignore <code>meta</code> field changes in config file watcher. (#13460) Thanks @brandonwise.</li>
+<li>Cron: use requested <code>agentId</code> for isolated job auth resolution. (#13983) Thanks @0xRaini.</li>
+<li>Cron: pass <code>agentId</code> to <code>runHeartbeatOnce</code> for main-session jobs. (#14140) Thanks @ishikawa-pro.</li>
+<li>Cron: prevent cron jobs from skipping execution when <code>nextRunAtMs</code> advances. (#14068) Thanks @WalterSumbon.</li>
+<li>Cron: re-arm timers when <code>onTimer</code> fires while a job is still executing. (#14233) Thanks @tomron87.</li>
+<li>Cron: prevent duplicate fires when multiple jobs trigger simultaneously. (#14256) Thanks @xinhuagu.</li>
+<li>Cron: isolate scheduler errors so one bad job does not break all jobs. (#14385) Thanks @MarvinDontPanic.</li>
+<li>Cron: prevent one-shot <code>at</code> jobs from re-firing on restart after skipped/errored runs. (#13878) Thanks @lailoo.</li>
+<li>Daemon: suppress <code>EPIPE</code> error when restarting LaunchAgent. (#14343) Thanks @0xRaini.</li>
+<li>Antigravity: add opus 4.6 forward-compat model and bypass thinking signature sanitization. (#14218) Thanks @jg-noncelogic.</li>
+<li>Agents: prevent file descriptor leaks in child process cleanup. (#13565) Thanks @KyleChen26.</li>
+<li>Agents: prevent double compaction caused by cache TTL bypassing guard. (#13514) Thanks @taw0002.</li>
+<li>Agents: use last API call's cache tokens for context display instead of accumulated sum. (#13805) Thanks @akari-musubi.</li>
+<li>Agents: keep followup-runner session <code>totalTokens</code> aligned with post-compaction context by using last-call usage and shared token-accounting logic. (#14979) Thanks @shtse8.</li>
+<li>Hooks/Plugins: wire 9 previously unwired plugin lifecycle hooks into core runtime paths (session, compaction, gateway, and outbound message hooks). (#14882) Thanks @shtse8.</li>
+<li>Hooks/Tools: dispatch <code>before_tool_call</code> and <code>after_tool_call</code> hooks from both tool execution paths with rebased conflict fixes. (#15012) Thanks @Patrick-Barletta, @Takhoffman.</li>
+<li>Discord: allow channel-edit to archive/lock threads and set auto-archive duration. (#5542) Thanks @stumct.</li>
+<li>Discord tests: use a partial @buape/carbon mock in slash command coverage. (#13262) Thanks @arosstale.</li>
+<li>Tests: update thread ID handling in Slack message collection tests. (#14108) Thanks @swizzmagik.</li>
+</ul>
+<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.12/OpenClaw-2026.2.12.zip" length="22877692" type="application/octet-stream" sparkle:edSignature="TGylTM4/7Lab+qp1nuPeOAmEVV1WkafXUPub8ws0z/0mYfbVygRuiev+u3zdPjQWhLnGYTgRgKVyW+kB2+Q2BQ=="/>
+        </item>
         <item>
             <title>2026.2.9</title>
             <pubDate>Mon, 09 Feb 2026 13:23:25 -0600</pubDate>
@@ -108,49 +204,5 @@
 ]]></description>
             <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.3/OpenClaw-2026.2.3.zip" length="22530161" type="application/octet-stream" sparkle:edSignature="7eHUaQC6cx87HWbcaPh9T437+LqfE9VtQBf4p9JBjIyBrqGYxxp9KPvI5unEjg55j9j2djCXhseSMeyyRmvYBg=="/>
         </item>
-        <item>
-            <title>2026.2.2</title>
-            <pubDate>Tue, 03 Feb 2026 17:04:17 -0800</pubDate>
-            <link>https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml</link>
-            <sparkle:version>8809</sparkle:version>
-            <sparkle:shortVersionString>2026.2.2</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>OpenClaw 2026.2.2</h2>
-<h3>Changes</h3>
-<ul>
-<li>Feishu: add Feishu/Lark plugin support + docs. (#7313) Thanks @jiulingyun (openclaw-cn).</li>
-<li>Web UI: add Agents dashboard for managing agent files, tools, skills, models, channels, and cron jobs.</li>
-<li>Memory: implement the opt-in QMD backend for workspace memory. (#3160) Thanks @vignesh07.</li>
-<li>Security: add healthcheck skill and bootstrap audit guidance. (#7641) Thanks @Takhoffman.</li>
-<li>Config: allow setting a default subagent thinking level via <code>agents.defaults.subagents.thinking</code> (and per-agent <code>agents.list[].subagents.thinking</code>). (#7372) Thanks @tyler6204.</li>
-<li>Docs: zh-CN translations seed + polish, pipeline guidance, nav/landing updates, and typo fixes. (#8202, #6995, #6619, #7242, #7303, #7415) Thanks @AaronWander, @taiyi747, @Explorer1092, @rendaoyuan, @joshp123, @lailoo.</li>
-</ul>
-<h3>Fixes</h3>
-<ul>
-<li>Security: require operator.approvals for gateway /approve commands. (#1) Thanks @mitsuhiko, @yueyueL.</li>
-<li>Security: Matrix allowlists now require full MXIDs; ambiguous name resolution no longer grants access. Thanks @MegaManSec.</li>
-<li>Security: enforce access-group gating for Slack slash commands when channel type lookup fails.</li>
-<li>Security: require validated shared-secret auth before skipping device identity on gateway connect.</li>
-<li>Security: guard skill installer downloads with SSRF checks (block private/localhost URLs).</li>
-<li>Security: harden Windows exec allowlist; block cmd.exe bypass via single &. Thanks @simecek.</li>
-<li>fix(voice-call): harden inbound allowlist; reject anonymous callers; require Telnyx publicKey for allowlist; token-gate Twilio media streams; cap webhook body size (thanks @simecek)</li>
-<li>Media understanding: apply SSRF guardrails to provider fetches; allow private baseUrl overrides explicitly.</li>
-<li>fix(webchat): respect user scroll position during streaming and refresh (#7226) (thanks @marcomarandiz)</li>
-<li>Telegram: recover from grammY long-poll timed out errors. (#7466) Thanks @macmimi23.</li>
-<li>Agents: repair malformed tool calls and session transcripts. (#7473) Thanks @justinhuangcode.</li>
-<li>fix(agents): validate AbortSignal instances before calling AbortSignal.any() (#7277) (thanks @Elarwei001)</li>
-<li>Media understanding: skip binary media from file text extraction. (#7475) Thanks @AlexZhangji.</li>
-<li>Onboarding: keep TUI flow exclusive (skip completion prompt + background Web UI seed); completion prompt now handled by install/update.</li>
-<li>TUI: block onboarding output while TUI is active and restore terminal state on exit.</li>
-<li>CLI/Zsh completion: cache scripts in state dir and escape option descriptions to avoid invalid option errors.</li>
-<li>fix(ui): resolve Control UI asset path correctly.</li>
-<li>fix(ui): refresh agent files after external edits.</li>
-<li>Docs: finish renaming the QMD memory docs to reference the OpenClaw state dir.</li>
-<li>Tests: stub SSRF DNS pinning in web auto-reply + Gemini video coverage. (#6619) Thanks @joshp123.</li>
-</ul>
-<p><a href="https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/openclaw/openclaw/releases/download/v2026.2.2/OpenClaw-2026.2.2.zip" length="22519052" type="application/octet-stream" sparkle:edSignature="a6viD+aS5EfY/RkPIPMfoQQNkJCk6QTdV5WobXFxyYwURskUm8/nXTHVXsCh1c5+0WKUnmlDIyf0i+6IWiavAA=="/>
-        </item>
     </channel>
 </rss>

apps/android/app/build.gradle.kts

@@ -21,8 +21,8 @@ android {
     applicationId = "ai.openclaw.android"
     minSdk = 31
     targetSdk = 36
-    versionCode = 202602030
-    versionName = "2026.2.9"
+    versionCode = 202602130
+    versionName = "2026.2.13"
   }
 
   buildTypes {

apps/ios/Sources/Info.plist

@@ -17,13 +17,13 @@
 	<key>CFBundleName</key>
 	<string>$(PRODUCT_NAME)</string>
 	<key>CFBundlePackageType</key>
-	<string>APPL</string>
-	<key>CFBundleShortVersionString</key>
-	<string>2026.2.9</string>
-	<key>CFBundleVersion</key>
-	<string>20260202</string>
-	<key>NSAppTransportSecurity</key>
-	<dict>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>2026.2.13</string>
+		<key>CFBundleVersion</key>
+		<string>20260213</string>
+		<key>NSAppTransportSecurity</key>
+		<dict>
 		<key>NSAllowsArbitraryLoadsInWebContent</key>
 		<true/>
 	</dict>

apps/ios/Tests/Info.plist

@@ -15,10 +15,10 @@
 	<key>CFBundleName</key>
 	<string>$(PRODUCT_NAME)</string>
 	<key>CFBundlePackageType</key>
-	<string>BNDL</string>
-	<key>CFBundleShortVersionString</key>
-	<string>2026.2.9</string>
-	<key>CFBundleVersion</key>
-	<string>20260202</string>
-</dict>
+		<string>BNDL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>2026.2.13</string>
+		<key>CFBundleVersion</key>
+		<string>20260213</string>
+	</dict>
 </plist>

apps/ios/project.yml

@@ -81,8 +81,8 @@ targets:
       properties:
         CFBundleDisplayName: OpenClaw
         CFBundleIconName: AppIcon
-        CFBundleShortVersionString: "2026.2.9"
-        CFBundleVersion: "20260202"
+        CFBundleShortVersionString: "2026.2.13"
+        CFBundleVersion: "20260213"
         UILaunchScreen: {}
         UIApplicationSceneManifest:
           UIApplicationSupportsMultipleScenes: false
@@ -130,5 +130,5 @@ targets:
       path: Tests/Info.plist
       properties:
         CFBundleDisplayName: OpenClawTests
-        CFBundleShortVersionString: "2026.2.9"
-        CFBundleVersion: "20260202"
+        CFBundleShortVersionString: "2026.2.13"
+        CFBundleVersion: "20260213"

apps/macos/Sources/OpenClaw/MenuSessionsInjector.swift

@@ -585,34 +585,38 @@ extension MenuSessionsInjector {
         let item = NSMenuItem()
         item.tag = self.tag
         item.isEnabled = false
-        let view = AnyView(SessionMenuPreviewView(
-            width: width,
-            maxLines: maxLines,
-            title: title,
-            items: [],
-            status: .loading))
-        let hosting = NSHostingView(rootView: view)
-        hosting.frame.size.width = max(1, width)
-        let size = hosting.fittingSize
-        hosting.frame = NSRect(origin: .zero, size: NSSize(width: width, height: size.height))
-        item.view = hosting
+        let view = AnyView(
+            SessionMenuPreviewView(
+                width: width,
+                maxLines: maxLines,
+                title: title,
+                items: [],
+                status: .loading)
+                .environment(\.isEnabled, true))
+        let hosted = HighlightedMenuItemHostView(rootView: view, width: width)
+        item.view = hosted
 
-        let task = Task { [weak hosting] in
+        let task = Task { [weak hosted, weak item] in
             let snapshot = await SessionMenuPreviewLoader.load(sessionKey: sessionKey, maxItems: 10)
             guard !Task.isCancelled else { return }
+
             await MainActor.run {
-                guard let hosting else { return }
-                let nextView = AnyView(SessionMenuPreviewView(
-                    width: width,
-                    maxLines: maxLines,
-                    title: title,
-                    items: snapshot.items,
-                    status: snapshot.status))
-                hosting.rootView = nextView
-                hosting.invalidateIntrinsicContentSize()
-                hosting.frame.size.width = max(1, width)
-                let size = hosting.fittingSize
-                hosting.frame.size.height = size.height
+                let nextView = AnyView(
+                    SessionMenuPreviewView(
+                        width: width,
+                        maxLines: maxLines,
+                        title: title,
+                        items: snapshot.items,
+                        status: snapshot.status)
+                        .environment(\.isEnabled, true))
+
+                if let item {
+                    item.view = HighlightedMenuItemHostView(rootView: nextView, width: width)
+                    return
+                }
+
+                guard let hosted else { return }
+                hosted.update(rootView: nextView, width: width)
             }
         }
         self.previewTasks.append(task)

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

@@ -15,9 +15,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>2026.2.9</string>
+    <string>2026.2.13</string>
     <key>CFBundleVersion</key>
-    <string>202602020</string>
+    <string>202602130</string>
     <key>CFBundleIconFile</key>
     <string>OpenClaw</string>
     <key>CFBundleURLTypes</key>

apps/macos/Sources/OpenClaw/VoiceWakeRuntime.swift

@@ -735,12 +735,13 @@ actor VoiceWakeRuntime {
     }
 
     private static func trimmedAfterTrigger(_ text: String, triggers: [String]) -> String {
-        let lower = text.lowercased()
         for trigger in triggers {
-            let token = trigger.lowercased().trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !token.isEmpty, let range = lower.range(of: token) else { continue }
-            let after = range.upperBound
-            let trimmed = text[after...].trimmingCharacters(in: .whitespacesAndNewlines)
+            let token = trigger.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !token.isEmpty else { continue }
+            guard let range = text.range(
+                of: token,
+                options: [.caseInsensitive, .diacriticInsensitive, .widthInsensitive]) else { continue }
+            let trimmed = text[range.upperBound...].trimmingCharacters(in: .whitespacesAndNewlines)
             return String(trimmed)
         }
         return text

apps/macos/Sources/OpenClawMacCLI/WizardCommand.swift

@@ -250,7 +250,8 @@ actor GatewayWizardClient {
         let clientId = "openclaw-macos"
         let clientMode = "ui"
         let role = "operator"
-        let scopes: [String] = []
+        // Explicit scopes; gateway no longer defaults empty scopes to admin.
+        let scopes: [String] = ["operator.admin", "operator.approvals", "operator.pairing"]
         let client: [String: ProtoAnyCodable] = [
             "id": ProtoAnyCodable(clientId),
             "displayName": ProtoAnyCodable(Host.current().localizedName ?? "OpenClaw macOS Wizard CLI"),

apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

@@ -1,4 +1,5 @@
 // Generated by scripts/protocol-gen-swift.ts — do not edit by hand
+// swiftlint:disable file_length
 import Foundation
 
 public let GATEWAY_PROTOCOL_VERSION = 3
@@ -383,7 +384,7 @@ public struct AgentEvent: Codable, Sendable {
 
 public struct SendParams: Codable, Sendable {
     public let to: String
-    public let message: String
+    public let message: String?
     public let mediaurl: String?
     public let mediaurls: [String]?
     public let gifplayback: Bool?
@@ -394,7 +395,7 @@ public struct SendParams: Codable, Sendable {
 
     public init(
         to: String,
-        message: String,
+        message: String?,
         mediaurl: String?,
         mediaurls: [String]?,
         gifplayback: Bool?,
@@ -488,6 +489,7 @@ public struct AgentParams: Codable, Sendable {
     public let timeout: Int?
     public let lane: String?
     public let extrasystemprompt: String?
+    public let inputprovenance: [String: AnyCodable]?
     public let idempotencykey: String
     public let label: String?
     public let spawnedby: String?
@@ -513,6 +515,7 @@ public struct AgentParams: Codable, Sendable {
         timeout: Int?,
         lane: String?,
         extrasystemprompt: String?,
+        inputprovenance: [String: AnyCodable]?,
         idempotencykey: String,
         label: String?,
         spawnedby: String?
@@ -537,6 +540,7 @@ public struct AgentParams: Codable, Sendable {
         self.timeout = timeout
         self.lane = lane
         self.extrasystemprompt = extrasystemprompt
+        self.inputprovenance = inputprovenance
         self.idempotencykey = idempotencykey
         self.label = label
         self.spawnedby = spawnedby
@@ -562,6 +566,7 @@ public struct AgentParams: Codable, Sendable {
         case timeout
         case lane
         case extrasystemprompt = "extraSystemPrompt"
+        case inputprovenance = "inputProvenance"
         case idempotencykey = "idempotencyKey"
         case label
         case spawnedby = "spawnedBy"

apps/macos/Tests/OpenClawIPCTests/VoiceWakeRuntimeTests.swift

@@ -35,6 +35,18 @@ import Testing
         #expect(VoiceWakeRuntime._testHasContentAfterTrigger(text, triggers: triggers))
     }
 
+    @Test func trimsAfterChineseTriggerKeepsPostSpeech() {
+        let triggers = ["小爪", "openclaw"]
+        let text = "嘿 小爪 帮我打开设置"
+        #expect(VoiceWakeRuntime._testTrimmedAfterTrigger(text, triggers: triggers) == "帮我打开设置")
+    }
+
+    @Test func trimsAfterTriggerHandlesWidthInsensitiveForms() {
+        let triggers = ["openclaw"]
+        let text = "ＯｐｅｎＣｌａｗ 请帮我"
+        #expect(VoiceWakeRuntime._testTrimmedAfterTrigger(text, triggers: triggers) == "请帮我")
+    }
+
     @Test func gateRequiresGapBetweenTriggerAndCommand() {
         let transcript = "hey openclaw do thing"
         let segments = makeSegments(

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

@@ -1,4 +1,5 @@
 // Generated by scripts/protocol-gen-swift.ts — do not edit by hand
+// swiftlint:disable file_length
 import Foundation
 
 public let GATEWAY_PROTOCOL_VERSION = 3
@@ -383,7 +384,7 @@ public struct AgentEvent: Codable, Sendable {
 
 public struct SendParams: Codable, Sendable {
     public let to: String
-    public let message: String
+    public let message: String?
     public let mediaurl: String?
     public let mediaurls: [String]?
     public let gifplayback: Bool?
@@ -394,7 +395,7 @@ public struct SendParams: Codable, Sendable {
 
     public init(
         to: String,
-        message: String,
+        message: String?,
         mediaurl: String?,
         mediaurls: [String]?,
         gifplayback: Bool?,
@@ -488,6 +489,7 @@ public struct AgentParams: Codable, Sendable {
     public let timeout: Int?
     public let lane: String?
     public let extrasystemprompt: String?
+    public let inputprovenance: [String: AnyCodable]?
     public let idempotencykey: String
     public let label: String?
     public let spawnedby: String?
@@ -513,6 +515,7 @@ public struct AgentParams: Codable, Sendable {
         timeout: Int?,
         lane: String?,
         extrasystemprompt: String?,
+        inputprovenance: [String: AnyCodable]?,
         idempotencykey: String,
         label: String?,
         spawnedby: String?
@@ -537,6 +540,7 @@ public struct AgentParams: Codable, Sendable {
         self.timeout = timeout
         self.lane = lane
         self.extrasystemprompt = extrasystemprompt
+        self.inputprovenance = inputprovenance
         self.idempotencykey = idempotencykey
         self.label = label
         self.spawnedby = spawnedby
@@ -562,6 +566,7 @@ public struct AgentParams: Codable, Sendable {
         case timeout
         case lane
         case extrasystemprompt = "extraSystemPrompt"
+        case inputprovenance = "inputProvenance"
         case idempotencykey = "idempotencyKey"
         case label
         case spawnedby = "spawnedBy"

docs/automation/hooks.md

@@ -41,12 +41,11 @@ The hooks system allows you to:
 
 ### Bundled Hooks
 
-OpenClaw ships with four bundled hooks that are automatically discovered:
+OpenClaw ships with three bundled hooks that are automatically discovered:
 
 - **💾 session-memory**: Saves session context to your agent workspace (default `~/.openclaw/workspace/memory/`) when you issue `/new`
 - **📝 command-logger**: Logs all command events to `~/.openclaw/logs/commands.log`
 - **🚀 boot-md**: Runs `BOOT.md` when the gateway starts (requires internal hooks enabled)
-- **😈 soul-evil**: Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance
 
 List available hooks:
 
@@ -527,42 +526,6 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 openclaw hooks enable command-logger
 ```
 
-### soul-evil
-
-Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
-
-**Events**: `agent:bootstrap`
-
-**Docs**: [SOUL Evil Hook](/hooks/soul-evil)
-
-**Output**: No files written; swaps happen in-memory only.
-
-**Enable**:
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-**Config**:
-
-```json
-{
-  "hooks": {
-    "internal": {
-      "enabled": true,
-      "entries": {
-        "soul-evil": {
-          "enabled": true,
-          "file": "SOUL_EVIL.md",
-          "chance": 0.1,
-          "purge": { "at": "21:00", "duration": "15m" }
-        }
-      }
-    }
-  }
-}
-```
-
 ### boot-md
 
 Runs `BOOT.md` when the gateway starts (after channels start).

docs/automation/webhook.md

@@ -18,6 +18,10 @@ Gateway can expose a small HTTP webhook endpoint for external triggers.
     enabled: true,
     token: "shared-secret",
     path: "/hooks",
+    // Optional: restrict explicit `agentId` routing to this allowlist.
+    // Omit or include "*" to allow any agent.
+    // Set [] to deny all explicit `agentId` routing.
+    allowedAgentIds: ["hooks", "main"],
   },
 }
 ```
@@ -33,7 +37,7 @@ Every request must include the hook token. Prefer headers:
 
 - `Authorization: Bearer <token>` (recommended)
 - `x-openclaw-token: <token>`
-- `?token=<token>` (deprecated; logs a warning and will be removed in a future major release)
+- Query-string tokens are rejected (`?token=...` returns `400`).
 
 ## Endpoints
 
@@ -61,6 +65,7 @@ Payload:
 {
   "message": "Run this",
   "name": "Email",
+  "agentId": "hooks",
   "sessionKey": "hook:email:msg-123",
   "wakeMode": "now",
   "deliver": true,
@@ -74,7 +79,8 @@ Payload:
 
 - `message` **required** (string): The prompt or message for the agent to process.
 - `name` optional (string): Human-readable name for the hook (e.g., "GitHub"), used as a prefix in session summaries.
-- `sessionKey` optional (string): The key used to identify the agent's session. Defaults to a random `hook:<uuid>`. Using a consistent key allows for a multi-turn conversation within the hook context.
+- `agentId` optional (string): Route this hook to a specific agent. Unknown IDs fall back to the default agent. When set, the hook runs using the resolved agent's workspace and configuration.
+- `sessionKey` optional (string): The key used to identify the agent's session. By default this field is rejected unless `hooks.allowRequestSessionKey=true`.
 - `wakeMode` optional (`now` | `next-heartbeat`): Whether to trigger an immediate heartbeat (default `now`) or wait for the next periodic check.
 - `deliver` optional (boolean): If `true`, the agent's response will be sent to the messaging channel. Defaults to `true`. Responses that are only heartbeat acknowledgments are automatically skipped.
 - `channel` optional (string): The messaging channel for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `mattermost` (plugin), `signal`, `imessage`, `msteams`. Defaults to `last`.
@@ -89,6 +95,40 @@ Effect:
 - Always posts a summary into the **main** session
 - If `wakeMode=now`, triggers an immediate heartbeat
 
+## Session key policy (breaking change)
+
+`/hooks/agent` payload `sessionKey` overrides are disabled by default.
+
+- Recommended: set a fixed `hooks.defaultSessionKey` and keep request overrides off.
+- Optional: allow request overrides only when needed, and restrict prefixes.
+
+Recommended config:
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "${OPENCLAW_HOOKS_TOKEN}",
+    defaultSessionKey: "hook:ingress",
+    allowRequestSessionKey: false,
+    allowedSessionKeyPrefixes: ["hook:"],
+  },
+}
+```
+
+Compatibility config (legacy behavior):
+
+```json5
+{
+  hooks: {
+    enabled: true,
+    token: "${OPENCLAW_HOOKS_TOKEN}",
+    allowRequestSessionKey: true,
+    allowedSessionKeyPrefixes: ["hook:"], // strongly recommended
+  },
+}
+```
+
 ### `POST /hooks/<name>` (mapped)
 
 Custom hook names are resolved via `hooks.mappings` (see configuration). A mapping can
@@ -104,6 +144,11 @@ Mapping options (summary):
 - TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
 - Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
   (`channel` defaults to `last` and falls back to WhatsApp).
+- `agentId` routes the hook to a specific agent; unknown IDs fall back to the default agent.
+- `hooks.allowedAgentIds` restricts explicit `agentId` routing. Omit it (or include `*`) to allow any agent. Set `[]` to deny explicit `agentId` routing.
+- `hooks.defaultSessionKey` sets the default session for hook agent runs when no explicit key is provided.
+- `hooks.allowRequestSessionKey` controls whether `/hooks/agent` payloads may set `sessionKey` (default: `false`).
+- `hooks.allowedSessionKeyPrefixes` optionally restricts explicit `sessionKey` values from request payloads and mappings.
 - `allowUnsafeExternalContent: true` disables the external content safety wrapper for that hook
   (dangerous; only for trusted internal sources).
 - `openclaw webhooks gmail setup` writes `hooks.gmail` config for `openclaw webhooks gmail run`.
@@ -114,6 +159,7 @@ Mapping options (summary):
 - `200` for `/hooks/wake`
 - `202` for `/hooks/agent` (async run started)
 - `401` on auth failure
+- `429` after repeated auth failures from the same client (check `Retry-After`)
 - `400` on invalid payload
 - `413` on oversized payloads
 
@@ -157,6 +203,10 @@ curl -X POST http://127.0.0.1:18789/hooks/gmail \
 
 - Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
 - Use a dedicated hook token; do not reuse gateway auth tokens.
+- Repeated auth failures are rate-limited per client address to slow brute-force attempts.
+- If you use multi-agent routing, set `hooks.allowedAgentIds` to limit explicit `agentId` selection.
+- Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.
+- If you enable request `sessionKey`, restrict `hooks.allowedSessionKeyPrefixes` (for example, `["hook:"]`).
 - Avoid including sensitive raw payloads in webhook logs.
 - Hook payloads are treated as untrusted and wrapped with safety boundaries by default.
   If you must disable this for a specific hook, set `allowUnsafeExternalContent: true`

docs/channels/discord.md

@@ -7,21 +7,32 @@ title: "Discord"
 
 # Discord (Bot API)
 
-Status: ready for DM and guild text channels via the official Discord bot gateway.
+Status: ready for DMs and guild channels via the official Discord gateway.
 
-## Quick setup (beginner)
+<CardGroup cols={3}>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    Discord DMs default to pairing mode.
+  </Card>
+  <Card title="Slash commands" icon="terminal" href="/tools/slash-commands">
+    Native command behavior and command catalog.
+  </Card>
+  <Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
+    Cross-channel diagnostics and repair flow.
+  </Card>
+</CardGroup>
 
-1. Create a Discord bot and copy the bot token.
-2. In the Discord app settings, enable **Message Content Intent** (and **Server Members Intent** if you plan to use allowlists or name lookups).
-3. Set the token for OpenClaw:
-   - Env: `DISCORD_BOT_TOKEN=...`
-   - Or config: `channels.discord.token: "..."`.
-   - If both are set, config takes precedence (env fallback is default-account only).
-4. Invite the bot to your server with message permissions (create a private server if you just want DMs).
-5. Start the gateway.
-6. DM access is pairing by default; approve the pairing code on first contact.
+## Quick setup
 
-Minimal config:
+<Steps>
+  <Step title="Create a Discord bot and enable intents">
+    Create an application in the Discord Developer Portal, add a bot, then enable:
+
+    - **Message Content Intent**
+    - **Server Members Intent** (required for role allowlists and role-based routing; recommended for name-to-ID allowlist matching)
+
+  </Step>
+
+  <Step title="Configure token">
 
 ```json5
 {
@@ -34,342 +45,293 @@ Minimal config:
 }
 ```
 
-## Goals
+    Env fallback for the default account:
 
-- Talk to OpenClaw via Discord DMs or guild channels.
-- Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
-- Group DMs are ignored by default; enable via `channels.discord.dm.groupEnabled` and optionally restrict by `channels.discord.dm.groupChannels`.
-- Keep routing deterministic: replies always go back to the channel they arrived on.
-
-## How it works
-
-1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
-2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
-3. Configure OpenClaw with `channels.discord.token` (or `DISCORD_BOT_TOKEN` as a fallback).
-4. Run the gateway; it auto-starts the Discord channel when a token is available (config first, env fallback) and `channels.discord.enabled` is not `false`.
-   - If you prefer env vars, set `DISCORD_BOT_TOKEN` (a config block is optional).
-5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session. Bare numeric IDs are ambiguous and rejected.
-6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
-7. Direct chats: secure by default via `channels.discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `openclaw pairing approve discord <code>`.
-   - To keep old “open to anyone” behavior: set `channels.discord.dm.policy="open"` and `channels.discord.dm.allowFrom=["*"]`.
-   - To hard-allowlist: set `channels.discord.dm.policy="allowlist"` and list senders in `channels.discord.dm.allowFrom`.
-   - To ignore all DMs: set `channels.discord.dm.enabled=false` or `channels.discord.dm.policy="disabled"`.
-8. Group DMs are ignored by default; enable via `channels.discord.dm.groupEnabled` and optionally restrict by `channels.discord.dm.groupChannels`.
-9. Optional guild rules: set `channels.discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
-10. Optional native commands: `commands.native` defaults to `"auto"` (on for Discord/Telegram, off for Slack). Override with `channels.discord.commands.native: true|false|"auto"`; `false` clears previously registered commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-    - Full command list + config: [Slash commands](/tools/slash-commands)
-11. Optional guild context history: set `channels.discord.historyLimit` (default 20, falls back to `messages.groupChat.historyLimit`) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
-12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `channels.discord.actions.*`).
-    - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-    - The `discord` tool is only exposed when the current channel is Discord.
-13. Native commands use isolated session keys (`agent:<agentId>:discord:slash:<userId>`) rather than the shared `main` session.
-
-Note: Name → id resolution uses guild member search and requires Server Members Intent; if the bot can’t search members, use ids or `<@id>` mentions.
-Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
-Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
-
-## Config writes
-
-By default, Discord is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
-
-Disable with:
-
-```json5
-{
-  channels: { discord: { configWrites: false } },
-}
+```bash
+DISCORD_BOT_TOKEN=...
 ```
 
-## How to create your own bot
+  </Step>
 
-This is the “Discord Developer Portal” setup for running OpenClaw in a server (guild) channel like `#help`.
+  <Step title="Invite the bot and start gateway">
+    Invite the bot to your server with message permissions.
 
-### 1) Create the Discord app + bot user
+```bash
+openclaw gateway
+```
 
-1. Discord Developer Portal → **Applications** → **New Application**
-2. In your app:
-   - **Bot** → **Add Bot**
-   - Copy the **Bot Token** (this is what you put in `DISCORD_BOT_TOKEN`)
+  </Step>
 
-### 2) Enable the gateway intents OpenClaw needs
+  <Step title="Approve first DM pairing">
 
-Discord blocks “privileged intents” unless you explicitly enable them.
+```bash
+openclaw pairing list discord
+openclaw pairing approve discord <CODE>
+```
 
-In **Bot** → **Privileged Gateway Intents**, enable:
+    Pairing codes expire after 1 hour.
 
-- **Message Content Intent** (required to read message text in most guilds; without it you’ll see “Used disallowed intents” or the bot will connect but not react to messages)
-- **Server Members Intent** (recommended; required for some member/user lookups and allowlist matching in guilds)
+  </Step>
+</Steps>
 
-You usually do **not** need **Presence Intent**. Setting the bot's own presence (`setPresence` action) uses gateway OP3 and does not require this intent; it is only needed if you want to receive presence updates about other guild members.
+<Note>
+Token resolution is account-aware. Config token values win over env fallback. `DISCORD_BOT_TOKEN` is only used for the default account.
+</Note>
 
-### 3) Generate an invite URL (OAuth2 URL Generator)
+## Runtime model
 
-In your app: **OAuth2** → **URL Generator**
+- Gateway owns the Discord connection.
+- Reply routing is deterministic: Discord inbound replies back to Discord.
+- By default (`session.dmScope=main`), direct chats share the agent main session (`agent:main:main`).
+- Guild channels are isolated session keys (`agent:<agentId>:discord:channel:<channelId>`).
+- Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).
+- Native slash commands run in isolated command sessions (`agent:<agentId>:discord:slash:<userId>`), while still carrying `CommandTargetSessionKey` to the routed conversation session.
 
-**Scopes**
+## Access control and routing
 
-- ✅ `bot`
-- ✅ `applications.commands` (required for native commands)
+<Tabs>
+  <Tab title="DM policy">
+    `channels.discord.dm.policy` controls DM access:
 
-**Bot Permissions** (minimal baseline)
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `channels.discord.dm.allowFrom` to include `"*"`)
+    - `disabled`
 
-- ✅ View Channels
-- ✅ Send Messages
-- ✅ Read Message History
-- ✅ Embed Links
-- ✅ Attach Files
-- ✅ Add Reactions (optional but recommended)
-- ✅ Use External Emojis / Stickers (optional; only if you want them)
+    If DM policy is not open, unknown users are blocked (or prompted for pairing in `pairing` mode).
 
-Avoid **Administrator** unless you’re debugging and fully trust the bot.
+    DM target format for delivery:
 
-Copy the generated URL, open it, pick your server, and install the bot.
+    - `user:<id>`
+    - `<@id>` mention
 
-### 4) Get the ids (guild/user/channel)
+    Bare numeric IDs are ambiguous and rejected unless an explicit user/channel target kind is provided.
 
-Discord uses numeric ids everywhere; OpenClaw config prefers ids.
+  </Tab>
 
-1. Discord (desktop/web) → **User Settings** → **Advanced** → enable **Developer Mode**
-2. Right-click:
-   - Server name → **Copy Server ID** (guild id)
-   - Channel (e.g. `#help`) → **Copy Channel ID**
-   - Your user → **Copy User ID**
+  <Tab title="Guild policy">
+    Guild handling is controlled by `channels.discord.groupPolicy`:
 
-### 5) Configure OpenClaw
+    - `open`
+    - `allowlist`
+    - `disabled`
 
-#### Token
+    Secure baseline when `channels.discord` exists is `allowlist`.
 
-Set the bot token via env var (recommended on servers):
+    `allowlist` behavior:
 
-- `DISCORD_BOT_TOKEN=...`
+    - guild must match `channels.discord.guilds` (`id` preferred, slug accepted)
+    - optional sender allowlists: `users` (IDs or names) and `roles` (role IDs only); if either is configured, senders are allowed when they match `users` OR `roles`
+    - if a guild has `channels` configured, non-listed channels are denied
+    - if a guild has no `channels` block, all channels in that allowlisted guild are allowed
 
-Or via config:
+    Example:
 
 ```json5
 {
   channels: {
     discord: {
-      enabled: true,
-      token: "YOUR_BOT_TOKEN",
-    },
-  },
-}
-```
-
-Multi-account support: use `channels.discord.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
-
-#### Allowlist + channel routing
-
-Example “single server, only allow me, only allow #help”:
-
-```json5
-{
-  channels: {
-    discord: {
-      enabled: true,
-      dm: { enabled: false },
+      groupPolicy: "allowlist",
       guilds: {
-        YOUR_GUILD_ID: {
-          users: ["YOUR_USER_ID"],
+        "123456789012345678": {
           requireMention: true,
+          users: ["987654321098765432"],
+          roles: ["123456789012345678"],
           channels: {
+            general: { allow: true },
             help: { allow: true, requireMention: true },
           },
         },
       },
-      retry: {
-        attempts: 3,
-        minDelayMs: 500,
-        maxDelayMs: 30000,
-        jitter: 0.1,
-      },
     },
   },
 }
 ```
 
-Notes:
+    If you only set `DISCORD_BOT_TOKEN` and do not create a `channels.discord` block, runtime fallback is `groupPolicy="open"` (with a warning in logs).
 
-- `requireMention: true` means the bot only replies when mentioned (recommended for shared channels).
-- `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions for guild messages.
-- Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
-- If `channels` is present, any channel not listed is denied by default.
-- Use a `"*"` channel entry to apply defaults across all channels; explicit channel entries override the wildcard.
-- Threads inherit parent channel config (allowlist, `requireMention`, skills, prompts, etc.) unless you add the thread channel id explicitly.
-- Owner hint: when a per-guild or per-channel `users` allowlist matches the sender, OpenClaw treats that sender as the owner in the system prompt. For a global owner across channels, set `commands.ownerAllowFrom`.
-- Bot-authored messages are ignored by default; set `channels.discord.allowBots=true` to allow them (own messages remain filtered).
-- Warning: If you allow replies to other bots (`channels.discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
+  </Tab>
 
-### 6) Verify it works
+  <Tab title="Mentions and group DMs">
+    Guild messages are mention-gated by default.
 
-1. Start the gateway.
-2. In your server channel, send: `@Krill hello` (or whatever your bot name is).
-3. If nothing happens: check **Troubleshooting** below.
+    Mention detection includes:
 
-### Troubleshooting
+    - explicit bot mention
+    - configured mention patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - implicit reply-to-bot behavior in supported cases
 
-- First: run `openclaw doctor` and `openclaw channels status --probe` (actionable warnings + quick audits).
-- **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
-- **Bot connects but never replies in a guild channel**:
-  - Missing **Message Content Intent**, or
-  - The bot lacks channel permissions (View/Send/Read History), or
-  - Your config requires mentions and you didn’t mention it, or
-  - Your guild/channel allowlist denies the channel/user.
-- **`requireMention: false` but still no replies**:
-- `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
-  - If you only set `DISCORD_BOT_TOKEN` and never create a `channels.discord` section, the runtime
-    defaults `groupPolicy` to `open`. Add `channels.discord.groupPolicy`,
-    `channels.defaults.groupPolicy`, or a guild/channel allowlist to lock it down.
-- `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
-- **Permission audits** (`channels status --probe`) only check numeric channel IDs. If you use slugs/names as `channels.discord.guilds.*.channels` keys, the audit can’t verify permissions.
-- **DMs don’t work**: `channels.discord.dm.enabled=false`, `channels.discord.dm.policy="disabled"`, or you haven’t been approved yet (`channels.discord.dm.policy="pairing"`).
-- **Exec approvals in Discord**: Discord supports a **button UI** for exec approvals in DMs (Allow once / Always allow / Deny). `/approve <id> ...` is only for forwarded approvals and won’t resolve Discord’s button prompts. If you see `❌ Failed to submit approval: Error: unknown approval id` or the UI never shows up, check:
-  - `channels.discord.execApprovals.enabled: true` in your config.
-  - Your Discord user ID is listed in `channels.discord.execApprovals.approvers` (the UI is only sent to approvers).
-  - Use the buttons in the DM prompt (**Allow once**, **Always allow**, **Deny**).
-  - See [Exec approvals](/tools/exec-approvals) and [Slash commands](/tools/slash-commands) for the broader approvals and command flow.
+    `requireMention` is configured per guild/channel (`channels.discord.guilds...`).
 
-## Capabilities & limits
+    Group DMs:
 
-- DMs and guild text channels (threads are treated as separate channels; voice not supported).
-- Typing indicators sent best-effort; message chunking uses `channels.discord.textChunkLimit` (default 2000) and splits tall replies by line count (`channels.discord.maxLinesPerMessage`, default 17).
-- Optional newline chunking: set `channels.discord.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking.
-- File uploads supported up to the configured `channels.discord.mediaMaxMb` (default 8 MB).
-- Mention-gated guild replies by default to avoid noisy bots.
-- Reply context is injected when a message references another message (quoted content + ids).
-- Native reply threading is **off by default**; enable with `channels.discord.replyToMode` and reply tags.
+    - default: ignored (`dm.groupEnabled=false`)
+    - optional allowlist via `dm.groupChannels` (channel IDs or slugs)
 
-## Retry policy
+  </Tab>
+</Tabs>
 
-Outbound Discord API calls retry on rate limits (429) using Discord `retry_after` when available, with exponential backoff and jitter. Configure via `channels.discord.retry`. See [Retry policy](/concepts/retry).
+### Role-based agent routing
 
-## Config
+Use `bindings[].match.roles` to route Discord guild members to different agents by role ID. Role-based bindings accept role IDs only and are evaluated after peer or parent-peer bindings and before guild-only bindings.
+
+```json5
+{
+  bindings: [
+    {
+      agentId: "opus",
+      match: {
+        channel: "discord",
+        guildId: "123456789012345678",
+        roles: ["111111111111111111"],
+      },
+    },
+    {
+      agentId: "sonnet",
+      match: {
+        channel: "discord",
+        guildId: "123456789012345678",
+      },
+    },
+  ],
+}
+```
+
+## Developer Portal setup
+
+<AccordionGroup>
+  <Accordion title="Create app and bot">
+
+    1. Discord Developer Portal -> **Applications** -> **New Application**
+    2. **Bot** -> **Add Bot**
+    3. Copy bot token
+
+  </Accordion>
+
+  <Accordion title="Privileged intents">
+    In **Bot -> Privileged Gateway Intents**, enable:
+
+    - Message Content Intent
+    - Server Members Intent (recommended)
+
+    Presence intent is optional and only required if you want to receive presence updates. Setting bot presence (`setPresence`) does not require enabling presence updates for members.
+
+  </Accordion>
+
+  <Accordion title="OAuth scopes and baseline permissions">
+    OAuth URL generator:
+
+    - scopes: `bot`, `applications.commands`
+
+    Typical baseline permissions:
+
+    - View Channels
+    - Send Messages
+    - Read Message History
+    - Embed Links
+    - Attach Files
+    - Add Reactions (optional)
+
+    Avoid `Administrator` unless explicitly needed.
+
+  </Accordion>
+
+  <Accordion title="Copy IDs">
+    Enable Discord Developer Mode, then copy:
+
+    - server ID
+    - channel ID
+    - user ID
+
+    Prefer numeric IDs in OpenClaw config for reliable audits and probes.
+
+  </Accordion>
+</AccordionGroup>
+
+## Native commands and command auth
+
+- `commands.native` defaults to `"auto"` and is enabled for Discord.
+- Per-channel override: `channels.discord.commands.native`.
+- `commands.native=false` explicitly clears previously registered Discord native commands.
+- Native command auth uses the same Discord allowlists/policies as normal message handling.
+- Commands may still be visible in Discord UI for users who are not authorized; execution still enforces OpenClaw auth and returns "not authorized".
+
+See [Slash commands](/tools/slash-commands) for command catalog and behavior.
+
+## Feature details
+
+<AccordionGroup>
+  <Accordion title="Reply tags and native replies">
+    Discord supports reply tags in agent output:
+
+    - `[[reply_to_current]]`
+    - `[[reply_to:<id>]]`
+
+    Controlled by `channels.discord.replyToMode`:
+
+    - `off` (default)
+    - `first`
+    - `all`
+
+    Message IDs are surfaced in context/history so agents can target specific messages.
+
+  </Accordion>
+
+  <Accordion title="History, context, and thread behavior">
+    Guild history context:
+
+    - `channels.discord.historyLimit` default `20`
+    - fallback: `messages.groupChat.historyLimit`
+    - `0` disables
+
+    DM history controls:
+
+    - `channels.discord.dmHistoryLimit`
+    - `channels.discord.dms["<user_id>"].historyLimit`
+
+    Thread behavior:
+
+    - Discord threads are routed as channel sessions
+    - parent thread metadata can be used for parent-session linkage
+    - thread config inherits parent channel config unless a thread-specific entry exists
+
+    Channel topics are injected as **untrusted** context (not as system prompt).
+
+  </Accordion>
+
+  <Accordion title="Reaction notifications">
+    Per-guild reaction notification mode:
+
+    - `off`
+    - `own` (default)
+    - `all`
+    - `allowlist` (uses `guilds.<id>.users`)
+
+    Reaction events are turned into system events and attached to the routed Discord session.
+
+  </Accordion>
+
+  <Accordion title="Config writes">
+    Channel-initiated config writes are enabled by default.
+
+    This affects `/config set|unset` flows (when command features are enabled).
+
+    Disable:
 
 ```json5
 {
   channels: {
     discord: {
-      enabled: true,
-      token: "abc.123",
-      groupPolicy: "allowlist",
-      guilds: {
-        "*": {
-          channels: {
-            general: { allow: true },
-          },
-        },
-      },
-      mediaMaxMb: 8,
-      actions: {
-        reactions: true,
-        stickers: true,
-        emojiUploads: true,
-        stickerUploads: true,
-        polls: true,
-        permissions: true,
-        messages: true,
-        threads: true,
-        pins: true,
-        search: true,
-        memberInfo: true,
-        roleInfo: true,
-        roles: false,
-        channelInfo: true,
-        channels: true,
-        voiceStatus: true,
-        events: true,
-        moderation: false,
-        presence: false,
-      },
-      replyToMode: "off",
-      dm: {
-        enabled: true,
-        policy: "pairing", // pairing | allowlist | open | disabled
-        allowFrom: ["123456789012345678", "steipete"],
-        groupEnabled: false,
-        groupChannels: ["openclaw-dm"],
-      },
-      guilds: {
-        "*": { requireMention: true },
-        "123456789012345678": {
-          slug: "friends-of-openclaw",
-          requireMention: false,
-          reactionNotifications: "own",
-          users: ["987654321098765432", "steipete"],
-          channels: {
-            general: { allow: true },
-            help: {
-              allow: true,
-              requireMention: true,
-              users: ["987654321098765432"],
-              skills: ["search", "docs"],
-              systemPrompt: "Keep answers short.",
-            },
-          },
-        },
-      },
+      configWrites: false,
     },
   },
 }
 ```
 
-Ack reactions are controlled globally via `messages.ackReaction` +
-`messages.ackReactionScope`. Use `messages.removeAckAfterReply` to clear the
-ack reaction after the bot replies.
+  </Accordion>
 
-- `dm.enabled`: set `false` to ignore all DMs (default `true`).
-- `dm.policy`: DM access control (`pairing` recommended). `"open"` requires `dm.allowFrom=["*"]`.
-- `dm.allowFrom`: DM allowlist (user ids or names). Used by `dm.policy="allowlist"` and for `dm.policy="open"` validation. The wizard accepts usernames and resolves them to ids when the bot can search members.
-- `dm.groupEnabled`: enable group DMs (default `false`).
-- `dm.groupChannels`: optional allowlist for group DM channel ids or slugs.
-- `groupPolicy`: controls guild channel handling (`open|disabled|allowlist`); `allowlist` requires channel allowlists.
-- `guilds`: per-guild rules keyed by guild id (preferred) or slug.
-- `guilds."*"`: default per-guild settings applied when no explicit entry exists.
-- `guilds.<id>.slug`: optional friendly slug used for display names.
-- `guilds.<id>.users`: optional per-guild user allowlist (ids or names).
-- `guilds.<id>.tools`: optional per-guild tool policy overrides (`allow`/`deny`/`alsoAllow`) used when the channel override is missing.
-- `guilds.<id>.toolsBySender`: optional per-sender tool policy overrides at the guild level (applies when the channel override is missing; `"*"` wildcard supported).
-- `guilds.<id>.channels.<channel>.allow`: allow/deny the channel when `groupPolicy="allowlist"`.
-- `guilds.<id>.channels.<channel>.requireMention`: mention gating for the channel.
-- `guilds.<id>.channels.<channel>.tools`: optional per-channel tool policy overrides (`allow`/`deny`/`alsoAllow`).
-- `guilds.<id>.channels.<channel>.toolsBySender`: optional per-sender tool policy overrides within the channel (`"*"` wildcard supported).
-- `guilds.<id>.channels.<channel>.users`: optional per-channel user allowlist.
-- `guilds.<id>.channels.<channel>.skills`: skill filter (omit = all skills, empty = none).
-- `guilds.<id>.channels.<channel>.systemPrompt`: extra system prompt for the channel. Discord channel topics are injected as **untrusted** context (not system prompt).
-- `guilds.<id>.channels.<channel>.enabled`: set `false` to disable the channel.
-- `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
-- `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
-- `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
-- `textChunkLimit`: outbound text chunk size (chars). Default: 2000.
-- `chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking.
-- `maxLinesPerMessage`: soft max line count per message. Default: 17.
-- `mediaMaxMb`: clamp inbound media saved to disk.
-- `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20; falls back to `messages.groupChat.historyLimit`; `0` disables).
-- `dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `dms["<user_id>"].historyLimit`.
-- `retry`: retry policy for outbound Discord API calls (attempts, minDelayMs, maxDelayMs, jitter).
-- `pluralkit`: resolve PluralKit proxied messages so system members appear as distinct senders.
-- `actions`: per-action tool gates; omit to allow all (set `false` to disable).
-  - `reactions` (covers react + read reactions)
-  - `stickers`, `emojiUploads`, `stickerUploads`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
-  - `memberInfo`, `roleInfo`, `channelInfo`, `voiceStatus`, `events`
-  - `channels` (create/edit/delete channels + categories + permissions)
-  - `roles` (role add/remove, default `false`)
-  - `moderation` (timeout/kick/ban, default `false`)
-  - `presence` (bot status/activity, default `false`)
-- `execApprovals`: Discord-only exec approval DMs (button UI). Supports `enabled`, `approvers`, `agentFilter`, `sessionFilter`, `cleanupAfterResolve`.
-
-Reaction notifications use `guilds.<id>.reactionNotifications`:
-
-- `off`: no reaction events.
-- `own`: reactions on the bot's own messages (default).
-- `all`: all reactions on all messages.
-- `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
-
-### PluralKit (PK) support
-
-Enable PK lookups so proxied messages resolve to the underlying system + member.
-When enabled, OpenClaw uses the member identity for allowlists and labels the
-sender as `Member (PK:System)` to avoid accidental Discord pings.
+  <Accordion title="PluralKit support">
+    Enable PluralKit resolution to map proxied messages to system member identity:
 
 ```json5
 {
@@ -377,100 +339,146 @@ sender as `Member (PK:System)` to avoid accidental Discord pings.
     discord: {
       pluralkit: {
         enabled: true,
-        token: "pk_live_...", // optional; required for private systems
+        token: "pk_live_...", // optional; needed for private systems
       },
     },
   },
 }
 ```
 
-Allowlist notes (PK-enabled):
+    Notes:
 
-- Use `pk:<memberId>` in `dm.allowFrom`, `guilds.<id>.users`, or per-channel `users`.
-- Member display names are also matched by name/slug.
-- Lookups use the **original** Discord message ID (the pre-proxy message), so
-  the PK API only resolves it within its 30-minute window.
-- If PK lookups fail (e.g., private system without a token), proxied messages
-  are treated as bot messages and are dropped unless `channels.discord.allowBots=true`.
+    - allowlists can use `pk:<memberId>`
+    - member display names are matched by name/slug
+    - lookups use original message ID and are time-window constrained
+    - if lookup fails, proxied messages are treated as bot messages and dropped unless `allowBots=true`
 
-### Tool action defaults
+  </Accordion>
 
-| Action group   | Default  | Notes                              |
-| -------------- | -------- | ---------------------------------- |
-| reactions      | enabled  | React + list reactions + emojiList |
-| stickers       | enabled  | Send stickers                      |
-| emojiUploads   | enabled  | Upload emojis                      |
-| stickerUploads | enabled  | Upload stickers                    |
-| polls          | enabled  | Create polls                       |
-| permissions    | enabled  | Channel permission snapshot        |
-| messages       | enabled  | Read/send/edit/delete              |
-| threads        | enabled  | Create/list/reply                  |
-| pins           | enabled  | Pin/unpin/list                     |
-| search         | enabled  | Message search (preview feature)   |
-| memberInfo     | enabled  | Member info                        |
-| roleInfo       | enabled  | Role list                          |
-| channelInfo    | enabled  | Channel info + list                |
-| channels       | enabled  | Channel/category management        |
-| voiceStatus    | enabled  | Voice state lookup                 |
-| events         | enabled  | List/create scheduled events       |
-| roles          | disabled | Role add/remove                    |
-| moderation     | disabled | Timeout/kick/ban                   |
-| presence       | disabled | Bot status/activity (setPresence)  |
+  <Accordion title="Exec approvals in Discord">
+    Discord supports button-based exec approvals in DMs.
 
-- `replyToMode`: `off` (default), `first`, or `all`. Applies only when the model includes a reply tag.
+    Config path:
 
-## Reply tags
+    - `channels.discord.execApprovals.enabled`
+    - `channels.discord.execApprovals.approvers`
+    - `agentFilter`, `sessionFilter`, `cleanupAfterResolve`
 
-To request a threaded reply, the model can include one tag in its output:
+    If approvals fail with unknown approval IDs, verify approver list and feature enablement.
 
-- `[[reply_to_current]]` — reply to the triggering Discord message.
-- `[[reply_to:<id>]]` — reply to a specific message id from context/history.
-  Current message ids are appended to prompts as `[message_id: …]`; history entries already include ids.
+    Related docs: [Exec approvals](/tools/exec-approvals)
 
-Behavior is controlled by `channels.discord.replyToMode`:
+  </Accordion>
+</AccordionGroup>
 
-- `off`: ignore tags.
-- `first`: only the first outbound chunk/attachment is a reply.
-- `all`: every outbound chunk/attachment is a reply.
+## Tools and action gates
 
-Allowlist matching notes:
+Discord message actions include messaging, channel admin, moderation, presence, and metadata actions.
 
-- `allowFrom`/`users`/`groupChannels` accept ids, names, tags, or mentions like `<@id>`.
-- Prefixes like `discord:`/`user:` (users) and `channel:` (group DMs) are supported.
-- Use `*` to allow any sender/channel.
-- When `guilds.<id>.channels` is present, channels not listed are denied by default.
-- When `guilds.<id>.channels` is omitted, all channels in the allowlisted guild are allowed.
-- To allow **no channels**, set `channels.discord.groupPolicy: "disabled"` (or keep an empty allowlist).
-- The configure wizard accepts `Guild/Channel` names (public + private) and resolves them to IDs when possible.
-- On startup, OpenClaw resolves channel/user names in allowlists to IDs (when the bot can search members)
-  and logs the mapping; unresolved entries are kept as typed.
+Core examples:
 
-Native command notes:
+- messaging: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply`
+- reactions: `react`, `reactions`, `emojiList`
+- moderation: `timeout`, `kick`, `ban`
+- presence: `setPresence`
 
-- The registered commands mirror OpenClaw’s chat commands.
-- Native commands honor the same allowlists as DMs/guild messages (`channels.discord.dm.allowFrom`, `channels.discord.guilds`, per-channel rules).
-- Slash commands may still be visible in Discord UI to users who aren’t allowlisted; OpenClaw enforces allowlists on execution and replies “not authorized”.
+Action gates live under `channels.discord.actions.*`.
 
-## Tool actions
+Default gate behavior:
 
-The agent can call `discord` with actions like:
+| Action group                                                                                                                                                             | Default  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled  |
+| roles                                                                                                                                                                    | disabled |
+| moderation                                                                                                                                                               | disabled |
+| presence                                                                                                                                                                 | disabled |
 
-- `react` / `reactions` (add or list reactions)
-- `sticker`, `poll`, `permissions`
-- `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
-- Read/search/pin tool payloads include normalized `timestampMs` (UTC epoch ms) and `timestampUtc` alongside raw Discord `timestamp`.
-- `threadCreate`, `threadList`, `threadReply`
-- `pinMessage`, `unpinMessage`, `listPins`
-- `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`
-- `channelInfo`, `channelList`, `voiceStatus`, `eventList`, `eventCreate`
-- `timeout`, `kick`, `ban`
-- `setPresence` (bot activity and online status)
+## Troubleshooting
 
-Discord message ids are surfaced in the injected context (`[discord message id: …]` and history lines) so the agent can target them.
-Emoji can be unicode (e.g., `✅`) or custom emoji syntax like `<:party_blob:1234567890>`.
+<AccordionGroup>
+  <Accordion title="Used disallowed intents or bot sees no guild messages">
 
-## Safety & ops
+    - enable Message Content Intent
+    - enable Server Members Intent when you depend on user/member resolution
+    - restart gateway after changing intents
 
-- Treat the bot token like a password; prefer the `DISCORD_BOT_TOKEN` env var on supervised hosts or lock down the config file permissions.
-- Only grant the bot permissions it needs (typically Read/Send Messages).
-- If the bot is stuck or rate limited, restart the gateway (`openclaw gateway --force`) after confirming no other processes own the Discord session.
+  </Accordion>
+
+  <Accordion title="Guild messages blocked unexpectedly">
+
+    - verify `groupPolicy`
+    - verify guild allowlist under `channels.discord.guilds`
+    - if guild `channels` map exists, only listed channels are allowed
+    - verify `requireMention` behavior and mention patterns
+
+    Useful checks:
+
+```bash
+openclaw doctor
+openclaw channels status --probe
+openclaw logs --follow
+```
+
+  </Accordion>
+
+  <Accordion title="Require mention false but still blocked">
+    Common causes:
+
+    - `groupPolicy="allowlist"` without matching guild/channel allowlist
+    - `requireMention` configured in the wrong place (must be under `channels.discord.guilds` or channel entry)
+    - sender blocked by guild/channel `users` allowlist
+
+  </Accordion>
+
+  <Accordion title="Permissions audit mismatches">
+    `channels status --probe` permission checks only work for numeric channel IDs.
+
+    If you use slug keys, runtime matching can still work, but probe cannot fully verify permissions.
+
+  </Accordion>
+
+  <Accordion title="DM and pairing issues">
+
+    - DM disabled: `channels.discord.dm.enabled=false`
+    - DM policy disabled: `channels.discord.dm.policy="disabled"`
+    - awaiting pairing approval in `pairing` mode
+
+  </Accordion>
+
+  <Accordion title="Bot to bot loops">
+    By default bot-authored messages are ignored.
+
+    If you set `channels.discord.allowBots=true`, use strict mention and allowlist rules to avoid loop behavior.
+
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+Primary reference:
+
+- [Configuration reference - Discord](/gateway/configuration-reference#discord)
+
+High-signal Discord fields:
+
+- startup/auth: `enabled`, `token`, `accounts.*`, `allowBots`
+- policy: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*`
+- command: `commands.native`, `commands.useAccessGroups`, `configWrites`
+- reply/history: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
+- delivery: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage`
+- media/retry: `mediaMaxMb`, `retry`
+- actions: `actions.*`
+- features: `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix`
+
+## Safety and operations
+
+- Treat bot tokens as secrets (`DISCORD_BOT_TOKEN` preferred in supervised environments).
+- Grant least-privilege Discord permissions.
+- If command deploy/state is stale, restart gateway and re-check with `openclaw channels status --probe`.
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Troubleshooting](/channels/troubleshooting)
+- [Slash commands](/tools/slash-commands)

docs/channels/imessage.md

@@ -3,26 +3,46 @@ summary: "Legacy iMessage support via imsg (JSON-RPC over stdio). New setups sho
 read_when:
   - Setting up iMessage support
   - Debugging iMessage send/receive
-title: iMessage
+title: "iMessage"
 ---
 
 # iMessage (legacy: imsg)
 
-> **Recommended:** Use [BlueBubbles](/channels/bluebubbles) for new iMessage setups.
->
-> The `imsg` channel is a legacy external-CLI integration and may be removed in a future release.
+<Warning>
+For new iMessage deployments, use <a href="/channels/bluebubbles">BlueBubbles</a>.
 
-Status: legacy external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).
+The `imsg` integration is legacy and may be removed in a future release.
+</Warning>
 
-## Quick setup (beginner)
+Status: legacy external CLI integration. Gateway spawns `imsg rpc` and communicates over JSON-RPC on stdio (no separate daemon/port).
 
-1. Ensure Messages is signed in on this Mac.
-2. Install `imsg`:
-   - `brew install steipete/tap/imsg`
-3. Configure OpenClaw with `channels.imessage.cliPath` and `channels.imessage.dbPath`.
-4. Start the gateway and approve any macOS prompts (Automation + Full Disk Access).
+<CardGroup cols={3}>
+  <Card title="BlueBubbles (recommended)" icon="message-circle" href="/channels/bluebubbles">
+    Preferred iMessage path for new setups.
+  </Card>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    iMessage DMs default to pairing mode.
+  </Card>
+  <Card title="Configuration reference" icon="settings" href="/gateway/configuration-reference#imessage">
+    Full iMessage field reference.
+  </Card>
+</CardGroup>
 
-Minimal config:
+## Quick setup
+
+<Tabs>
+  <Tab title="Local Mac (fast path)">
+    <Steps>
+      <Step title="Install and verify imsg">
+
+```bash
+brew install steipete/tap/imsg
+imsg rpc --help
+```
+
+      </Step>
+
+      <Step title="Configure OpenClaw">
 
 ```json5
 {
@@ -36,45 +56,65 @@ Minimal config:
 }
 ```
 
-## What it is
+      </Step>
 
-- iMessage channel backed by `imsg` on macOS.
-- Deterministic routing: replies always go back to iMessage.
-- DMs share the agent's main session; groups are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
-- If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `channels.imessage.groups` (see “Group-ish threads” below).
+      <Step title="Start gateway">
 
-## Config writes
+```bash
+openclaw gateway
+```
 
-By default, iMessage is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+      </Step>
 
-Disable with:
+      <Step title="Approve first DM pairing (default dmPolicy)">
+
+```bash
+openclaw pairing list imessage
+openclaw pairing approve imessage <CODE>
+```
+
+        Pairing requests expire after 1 hour.
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Remote Mac over SSH">
+    OpenClaw only requires a stdio-compatible `cliPath`, so you can point `cliPath` at a wrapper script that SSHes to a remote Mac and runs `imsg`.
+
+```bash
+#!/usr/bin/env bash
+exec ssh -T gateway-host imsg "$@"
+```
+
+    Recommended config when attachments are enabled:
 
 ```json5
 {
-  channels: { imessage: { configWrites: false } },
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "~/.openclaw/scripts/imsg-ssh",
+      remoteHost: "user@gateway-host", // used for SCP attachment fetches
+      includeAttachments: true,
+    },
+  },
 }
 ```
 
-## Requirements
+    If `remoteHost` is not set, OpenClaw attempts to auto-detect it by parsing the SSH wrapper script.
 
-- macOS with Messages signed in.
-- Full Disk Access for OpenClaw + `imsg` (Messages DB access).
-- 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`).
+  </Tab>
+</Tabs>
 
-## Troubleshooting macOS Privacy and Security TCC
+## Requirements and permissions (macOS)
 
-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.
+- Messages must be signed in on the Mac running `imsg`.
+- Full Disk Access is required for the process context running OpenClaw/`imsg` (Messages DB access).
+- Automation permission is required to send messages through Messages.app.
 
-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:
+<Tip>
+Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:
 
 ```bash
 imsg chats --limit 1
@@ -82,128 +122,87 @@ imsg chats --limit 1
 imsg send <handle> "test"
 ```
 
-Related macOS folder permissions (Desktop/Documents/Downloads): [/platforms/mac/permissions](/platforms/mac/permissions).
+</Tip>
 
-## Setup (fast path)
+## Access control and routing
 
-1. Ensure Messages is signed in on this Mac.
-2. Configure iMessage and start the gateway.
+<Tabs>
+  <Tab title="DM policy">
+    `channels.imessage.dmPolicy` controls direct messages:
 
-### Dedicated bot macOS user (for isolated identity)
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `allowFrom` to include `"*"`)
+    - `disabled`
 
-If you want the bot to send from a **separate iMessage identity** (and keep your personal Messages clean), use a dedicated Apple ID + a dedicated macOS user.
+    Allowlist field: `channels.imessage.allowFrom`.
 
-1. Create a dedicated Apple ID (example: `my-cool-bot@icloud.com`).
-   - Apple may require a phone number for verification / 2FA.
-2. Create a macOS user (example: `openclawhome`) and sign into it.
-3. Open Messages in that macOS user and sign into iMessage using the bot Apple ID.
-4. Enable Remote Login (System Settings → General → Sharing → Remote Login).
-5. Install `imsg`:
-   - `brew install steipete/tap/imsg`
-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.
+    Allowlist entries can be handles or chat targets (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
 
-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).
+  </Tab>
 
-Example wrapper (`chmod +x`). Replace `<bot-macos-user>` with your actual macOS username:
+  <Tab title="Group policy + mentions">
+    `channels.imessage.groupPolicy` controls group handling:
 
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
+    - `allowlist` (default when configured)
+    - `open`
+    - `disabled`
 
-# Run an interactive SSH once first to accept host keys:
-#   ssh <bot-macos-user>@localhost true
-exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
-  "/usr/local/bin/imsg" "$@"
-```
+    Group sender allowlist: `channels.imessage.groupAllowFrom`.
 
-Example config:
+    Runtime fallback: if `groupAllowFrom` is unset, iMessage group sender checks fall back to `allowFrom` when available.
 
-```json5
-{
-  channels: {
-    imessage: {
-      enabled: true,
-      accounts: {
-        bot: {
-          name: "Bot",
-          enabled: true,
-          cliPath: "/path/to/imsg-bot",
-          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db",
-        },
-      },
-    },
-  },
-}
-```
+    Mention gating for groups:
 
-For single-account setups, use flat options (`channels.imessage.cliPath`, `channels.imessage.dbPath`) instead of the `accounts` map.
+    - iMessage has no native mention metadata
+    - mention detection uses regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - with no configured patterns, mention gating cannot be enforced
 
-### Remote/SSH variant (optional)
+    Control commands from authorized senders can bypass mention gating in groups.
 
-If you want iMessage on another Mac, set `channels.imessage.cliPath` to a wrapper that runs `imsg` on the remote macOS host over SSH. OpenClaw only needs stdio.
+  </Tab>
 
-Example wrapper:
+  <Tab title="Sessions and deterministic replies">
+    - DMs use direct routing; groups use group routing.
+    - With default `session.dmScope=main`, iMessage DMs collapse into the agent main session.
+    - Group sessions are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
+    - Replies route back to iMessage using originating channel/target metadata.
 
-```bash
-#!/usr/bin/env bash
-exec ssh -T gateway-host imsg "$@"
-```
+    Group-ish thread behavior:
 
-**Remote attachments:** When `cliPath` points to a remote host via SSH, attachment paths in the Messages database reference files on the remote machine. OpenClaw can automatically fetch these over SCP by setting `channels.imessage.remoteHost`:
+    Some multi-participant iMessage threads can arrive with `is_group=false`.
+    If that `chat_id` is explicitly configured under `channels.imessage.groups`, OpenClaw treats it as group traffic (group gating + group session isolation).
 
-```json5
-{
-  channels: {
-    imessage: {
-      cliPath: "~/imsg-ssh", // SSH wrapper to remote Mac
-      remoteHost: "user@gateway-host", // for SCP file transfer
-      includeAttachments: true,
-    },
-  },
-}
-```
+  </Tab>
+</Tabs>
 
-If `remoteHost` is not set, OpenClaw attempts to auto-detect it by parsing the SSH command in your wrapper script. Explicit configuration is recommended for reliability.
+## Deployment patterns
 
-#### Remote Mac via Tailscale (example)
+<AccordionGroup>
+  <Accordion title="Dedicated bot macOS user (separate iMessage identity)">
+    Use a dedicated Apple ID and macOS user so bot traffic is isolated from your personal Messages profile.
 
-If the Gateway runs on a Linux host/VM but iMessage must run on a Mac, Tailscale is the simplest bridge: the Gateway talks to the Mac over the tailnet, runs `imsg` via SSH, and SCPs attachments back.
+    Typical flow:
 
-Architecture:
+    1. Create/sign in a dedicated macOS user.
+    2. Sign into Messages with the bot Apple ID in that user.
+    3. Install `imsg` in that user.
+    4. Create SSH wrapper so OpenClaw can run `imsg` in that user context.
+    5. Point `channels.imessage.accounts.<id>.cliPath` and `.dbPath` to that user profile.
 
-```mermaid
-%%{init: {
-  'theme': 'base',
-  'themeVariables': {
-    'primaryColor': '#ffffff',
-    'primaryTextColor': '#000000',
-    'primaryBorderColor': '#000000',
-    'lineColor': '#000000',
-    'secondaryColor': '#f9f9fb',
-    'tertiaryColor': '#ffffff',
-    'clusterBkg': '#f9f9fb',
-    'clusterBorder': '#000000',
-    'nodeBorder': '#000000',
-    'mainBkg': '#ffffff',
-    'edgeLabelBackground': '#ffffff'
-  }
-}}%%
-flowchart TB
- subgraph T[" "]
- subgraph Tailscale[" "]
-    direction LR
-      Gateway["<b>Gateway host (Linux/VM)<br></b><br>openclaw gateway<br>channels.imessage.cliPath"]
-      Mac["<b>Mac with Messages + imsg<br></b><br>Messages signed in<br>Remote Login enabled"]
-  end
-    Gateway -- SSH (imsg rpc) --> Mac
-    Mac -- SCP (attachments) --> Gateway
-    direction BT
-    User["user@gateway-host"] -- "Tailscale tailnet (hostname or 100.x.y.z)" --> Gateway
-end
-```
+    First run may require GUI approvals (Automation + Full Disk Access) in that bot user session.
 
-Concrete config example (Tailscale hostname):
+  </Accordion>
+
+  <Accordion title="Remote Mac over Tailscale (example)">
+    Common topology:
+
+    - gateway runs on Linux/VM
+    - iMessage + `imsg` runs on a Mac in your tailnet
+    - `cliPath` wrapper uses SSH to run `imsg`
+    - `remoteHost` enables SCP attachment fetches
+
+    Example:
 
 ```json5
 {
@@ -219,122 +218,134 @@ Concrete config example (Tailscale hostname):
 }
 ```
 
-Example wrapper (`~/.openclaw/scripts/imsg-ssh`):
-
 ```bash
 #!/usr/bin/env bash
 exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
 ```
 
-Notes:
+    Use SSH keys so both SSH and SCP are non-interactive.
 
-- Ensure the Mac is signed in to Messages, and Remote Login is enabled.
-- Use SSH keys so `ssh bot@mac-mini.tailnet-1234.ts.net` works without prompts.
-- `remoteHost` should match the SSH target so SCP can fetch attachments.
+  </Accordion>
 
-Multi-account support: use `channels.imessage.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. Don't commit `~/.openclaw/openclaw.json` (it often contains tokens).
+  <Accordion title="Multi-account pattern">
+    iMessage supports per-account config under `channels.imessage.accounts`.
 
-## Access control (DMs + groups)
+    Each account can override fields such as `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, and history settings.
 
-DMs:
+  </Accordion>
+</AccordionGroup>
 
-- Default: `channels.imessage.dmPolicy = "pairing"`.
-- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
-- Approve via:
-  - `openclaw pairing list imessage`
-  - `openclaw pairing approve imessage <CODE>`
-- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/channels/pairing)
+## Media, chunking, and delivery targets
 
-Groups:
+<AccordionGroup>
+  <Accordion title="Attachments and media">
+    - inbound attachment ingestion is optional: `channels.imessage.includeAttachments`
+    - remote attachment paths can be fetched via SCP when `remoteHost` is set
+    - outbound media size uses `channels.imessage.mediaMaxMb` (default 16 MB)
+  </Accordion>
 
-- `channels.imessage.groupPolicy = open | allowlist | disabled`.
-- `channels.imessage.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
-- Mention gating uses `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) because iMessage has no native mention metadata.
-- Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
+  <Accordion title="Outbound chunking">
+    - text chunk limit: `channels.imessage.textChunkLimit` (default 4000)
+    - chunk mode: `channels.imessage.chunkMode`
+      - `length` (default)
+      - `newline` (paragraph-first splitting)
+  </Accordion>
 
-## How it works (behavior)
+  <Accordion title="Addressing formats">
+    Preferred explicit targets:
 
-- `imsg` streams message events; the gateway normalizes them into the shared channel envelope.
-- Replies always route back to the same chat id or handle.
+    - `chat_id:123` (recommended for stable routing)
+    - `chat_guid:...`
+    - `chat_identifier:...`
 
-## Group-ish threads (`is_group=false`)
+    Handle targets are also supported:
 
-Some iMessage threads can have multiple participants but still arrive with `is_group=false` depending on how Messages stores the chat identifier.
+    - `imessage:+1555...`
+    - `sms:+1555...`
+    - `user@example.com`
 
-If you explicitly configure a `chat_id` under `channels.imessage.groups`, OpenClaw treats that thread as a “group” for:
+```bash
+imsg chats --limit 20
+```
 
-- session isolation (separate `agent:<agentId>:imessage:group:<chat_id>` session key)
-- group allowlisting / mention gating behavior
+  </Accordion>
+</AccordionGroup>
 
-Example:
+## Config writes
+
+iMessage allows channel-initiated config writes by default (for `/config set|unset` when `commands.config: true`).
+
+Disable:
 
 ```json5
 {
   channels: {
     imessage: {
-      groupPolicy: "allowlist",
-      groupAllowFrom: ["+15555550123"],
-      groups: {
-        "42": { requireMention: false },
-      },
+      configWrites: false,
     },
   },
 }
 ```
 
-This is useful when you want an isolated personality/model for a specific thread (see [Multi-agent routing](/concepts/multi-agent)). For filesystem isolation, see [Sandboxing](/gateway/sandboxing).
+## Troubleshooting
 
-## Media + limits
+<AccordionGroup>
+  <Accordion title="imsg not found or RPC unsupported">
+    Validate the binary and RPC support:
 
-- Optional attachment ingestion via `channels.imessage.includeAttachments`.
-- Media cap via `channels.imessage.mediaMaxMb`.
-
-## Limits
-
-- Outbound text is chunked to `channels.imessage.textChunkLimit` (default 4000).
-- Optional newline chunking: set `channels.imessage.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking.
-- Media uploads are capped by `channels.imessage.mediaMaxMb` (default 16).
-
-## Addressing / delivery targets
-
-Prefer `chat_id` for stable routing:
-
-- `chat_id:123` (preferred)
-- `chat_guid:...`
-- `chat_identifier:...`
-- direct handles: `imessage:+1555` / `sms:+1555` / `user@example.com`
-
-List chats:
-
-```
-imsg chats --limit 20
+```bash
+imsg rpc --help
+openclaw channels status --probe
 ```
 
-## Configuration reference (iMessage)
+    If probe reports RPC unsupported, update `imsg`.
 
-Full configuration: [Configuration](/gateway/configuration)
+  </Accordion>
 
-Provider options:
+  <Accordion title="DMs are ignored">
+    Check:
 
-- `channels.imessage.enabled`: enable/disable channel startup.
-- `channels.imessage.cliPath`: path to `imsg`.
-- `channels.imessage.dbPath`: Messages DB path.
-- `channels.imessage.remoteHost`: SSH host for SCP attachment transfer when `cliPath` points to a remote Mac (e.g., `user@gateway-host`). Auto-detected from SSH wrapper if not set.
-- `channels.imessage.service`: `imessage | sms | auto`.
-- `channels.imessage.region`: SMS region.
-- `channels.imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
-- `channels.imessage.allowFrom`: DM allowlist (handles, emails, E.164 numbers, or `chat_id:*`). `open` requires `"*"`. iMessage has no usernames; use handles or chat targets.
-- `channels.imessage.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
-- `channels.imessage.groupAllowFrom`: group sender allowlist.
-- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`: max group messages to include as context (0 disables).
-- `channels.imessage.dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `channels.imessage.dms["<handle>"].historyLimit`.
-- `channels.imessage.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
-- `channels.imessage.includeAttachments`: ingest attachments into context.
-- `channels.imessage.mediaMaxMb`: inbound/outbound media cap (MB).
-- `channels.imessage.textChunkLimit`: outbound chunk size (chars).
-- `channels.imessage.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking.
+    - `channels.imessage.dmPolicy`
+    - `channels.imessage.allowFrom`
+    - pairing approvals (`openclaw pairing list imessage`)
 
-Related global options:
+  </Accordion>
 
-- `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`).
-- `messages.responsePrefix`.
+  <Accordion title="Group messages are ignored">
+    Check:
+
+    - `channels.imessage.groupPolicy`
+    - `channels.imessage.groupAllowFrom`
+    - `channels.imessage.groups` allowlist behavior
+    - mention pattern configuration (`agents.list[].groupChat.mentionPatterns`)
+
+  </Accordion>
+
+  <Accordion title="Remote attachments fail">
+    Check:
+
+    - `channels.imessage.remoteHost`
+    - SSH/SCP key auth from the gateway host
+    - remote path readability on the Mac running Messages
+
+  </Accordion>
+
+  <Accordion title="macOS permission prompts were missed">
+    Re-run in an interactive GUI terminal in the same user/session context and approve prompts:
+
+```bash
+imsg chats --limit 1
+imsg send <handle> "test"
+```
+
+    Confirm Full Disk Access + Automation are granted for the process context that runs OpenClaw/`imsg`.
+
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+- [Configuration reference - iMessage](/gateway/configuration-reference#imessage)
+- [Gateway configuration](/gateway/configuration)
+- [Pairing](/channels/pairing)
+- [BlueBubbles](/channels/bluebubbles)

docs/channels/index.md

@@ -16,6 +16,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
 - [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
 - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
+- [IRC](/channels/irc) — Classic IRC servers; channels + DMs with pairing/allowlist controls.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
 - [Feishu](/channels/feishu) — Feishu/Lark bot via WebSocket (plugin, installed separately).
 - [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.

docs/channels/irc.md

@@ -0,0 +1,234 @@
+---
+title: IRC
+description: Connect OpenClaw to IRC channels and direct messages.
+---
+
+Use IRC when you want OpenClaw in classic channels (`#room`) and direct messages.
+IRC ships as an extension plugin, but it is configured in the main config under `channels.irc`.
+
+## Quick start
+
+1. Enable IRC config in `~/.openclaw/openclaw.json`.
+2. Set at least:
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "host": "irc.libera.chat",
+      "port": 6697,
+      "tls": true,
+      "nick": "openclaw-bot",
+      "channels": ["#openclaw"]
+    }
+  }
+}
+```
+
+3. Start/restart gateway:
+
+```bash
+openclaw gateway run
+```
+
+## Security defaults
+
+- `channels.irc.dmPolicy` defaults to `"pairing"`.
+- `channels.irc.groupPolicy` defaults to `"allowlist"`.
+- With `groupPolicy="allowlist"`, set `channels.irc.groups` to define allowed channels.
+- Use TLS (`channels.irc.tls=true`) unless you intentionally accept plaintext transport.
+
+## Access control
+
+There are two separate “gates” for IRC channels:
+
+1. **Channel access** (`groupPolicy` + `groups`): whether the bot accepts messages from a channel at all.
+2. **Sender access** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): who is allowed to trigger the bot inside that channel.
+
+Config keys:
+
+- DM allowlist (DM sender access): `channels.irc.allowFrom`
+- Group sender allowlist (channel sender access): `channels.irc.groupAllowFrom`
+- Per-channel controls (channel + sender + mention rules): `channels.irc.groups["#channel"]`
+- `channels.irc.groupPolicy="open"` allows unconfigured channels (**still mention-gated by default**)
+
+Allowlist entries can use nick or `nick!user@host` forms.
+
+### Common gotcha: `allowFrom` is for DMs, not channels
+
+If you see logs like:
+
+- `irc: drop group sender alice!ident@host (policy=allowlist)`
+
+…it means the sender wasn’t allowed for **group/channel** messages. Fix it by either:
+
+- setting `channels.irc.groupAllowFrom` (global for all channels), or
+- setting per-channel sender allowlists: `channels.irc.groups["#channel"].allowFrom`
+
+Example (allow anyone in `#tuirc-dev` to talk to the bot):
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": { allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Reply triggering (mentions)
+
+Even if a channel is allowed (via `groupPolicy` + `groups`) and the sender is allowed, OpenClaw defaults to **mention-gating** in group contexts.
+
+That means you may see logs like `drop channel … (missing-mention)` unless the message includes a mention pattern that matches the bot.
+
+To make the bot reply in an IRC channel **without needing a mention**, disable mention gating for that channel:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "allowlist",
+      groups: {
+        "#tuirc-dev": {
+          requireMention: false,
+          allowFrom: ["*"],
+        },
+      },
+    },
+  },
+}
+```
+
+Or to allow **all** IRC channels (no per-channel allowlist) and still reply without mentions:
+
+```json5
+{
+  channels: {
+    irc: {
+      groupPolicy: "open",
+      groups: {
+        "*": { requireMention: false, allowFrom: ["*"] },
+      },
+    },
+  },
+}
+```
+
+## Security note (recommended for public channels)
+
+If you allow `allowFrom: ["*"]` in a public channel, anyone can prompt the bot.
+To reduce risk, restrict tools for that channel.
+
+### Same tools for everyone in the channel
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          tools: {
+            deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+### Different tools per sender (owner gets more power)
+
+Use `toolsBySender` to apply a stricter policy to `"*"` and a looser one to your nick:
+
+```json5
+{
+  channels: {
+    irc: {
+      groups: {
+        "#tuirc-dev": {
+          allowFrom: ["*"],
+          toolsBySender: {
+            "*": {
+              deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
+            },
+            eigen: {
+              deny: ["gateway", "nodes", "cron"],
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- `toolsBySender` keys can be a nick (e.g. `"eigen"`) or a full hostmask (`"eigen!~eigen@174.127.248.171"`) for stronger identity matching.
+- The first matching sender policy wins; `"*"` is the wildcard fallback.
+
+For more on group access vs mention-gating (and how they interact), see: [/channels/groups](/channels/groups).
+
+## NickServ
+
+To identify with NickServ after connect:
+
+```json
+{
+  "channels": {
+    "irc": {
+      "nickserv": {
+        "enabled": true,
+        "service": "NickServ",
+        "password": "your-nickserv-password"
+      }
+    }
+  }
+}
+```
+
+Optional one-time registration on connect:
+
+```json
+{
+  "channels": {
+    "irc": {
+      "nickserv": {
+        "register": true,
+        "registerEmail": "bot@example.com"
+      }
+    }
+  }
+}
+```
+
+Disable `register` after the nick is registered to avoid repeated REGISTER attempts.
+
+## Environment variables
+
+Default account supports:
+
+- `IRC_HOST`
+- `IRC_PORT`
+- `IRC_TLS`
+- `IRC_NICK`
+- `IRC_USERNAME`
+- `IRC_REALNAME`
+- `IRC_PASSWORD`
+- `IRC_CHANNELS` (comma-separated)
+- `IRC_NICKSERV_PASSWORD`
+- `IRC_NICKSERV_REGISTER_EMAIL`
+
+## Troubleshooting
+
+- If the bot connects but never replies in channels, verify `channels.irc.groups` **and** whether mention-gating is dropping messages (`missing-mention`). If you want it to reply without pings, set `requireMention:false` for the channel.
+- If login fails, verify nick availability and server password.
+- If TLS fails on a custom network, verify host/port and certificate setup.

docs/channels/pairing.md

@@ -36,7 +36,7 @@ openclaw pairing list telegram
 openclaw pairing approve telegram <CODE>
 ```
 
-Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
+Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`, `feishu`.
 
 ### Where the state lives
 

docs/channels/slack.md

@@ -1,26 +1,47 @@
 ---
-summary: "Slack setup for socket or HTTP webhook mode"
-read_when: "Setting up Slack or debugging Slack socket/HTTP mode"
+summary: "Slack setup and runtime behavior (Socket Mode + HTTP Events API)"
+read_when:
+  - Setting up Slack or debugging Slack socket/HTTP mode
 title: "Slack"
 ---
 
 # Slack
 
-## Socket mode (default)
+Status: production-ready for DMs + channels via Slack app integrations. Default mode is Socket Mode; HTTP Events API mode is also supported.
 
-### Quick setup (beginner)
+<CardGroup cols={3}>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    Slack DMs default to pairing mode.
+  </Card>
+  <Card title="Slash commands" icon="terminal" href="/tools/slash-commands">
+    Native command behavior and command catalog.
+  </Card>
+  <Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
+    Cross-channel diagnostics and repair playbooks.
+  </Card>
+</CardGroup>
 
-1. Create a Slack app and enable **Socket Mode**.
-2. Create an **App Token** (`xapp-...`) and **Bot Token** (`xoxb-...`).
-3. Set tokens for OpenClaw and start the gateway.
+## Quick setup
 
-Minimal config:
+<Tabs>
+  <Tab title="Socket Mode (default)">
+    <Steps>
+      <Step title="Create Slack app and tokens">
+        In Slack app settings:
+
+        - enable **Socket Mode**
+        - create **App Token** (`xapp-...`) with `connections:write`
+        - install app and copy **Bot Token** (`xoxb-...`)
+      </Step>
+
+      <Step title="Configure OpenClaw">
 
 ```json5
 {
   channels: {
     slack: {
       enabled: true,
+      mode: "socket",
       appToken: "xapp-...",
       botToken: "xoxb-...",
     },
@@ -28,121 +49,50 @@ Minimal config:
 }
 ```
 
-### Setup
+        Env fallback (default account only):
 
-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-...`).
-5. **Event Subscriptions** → enable events and subscribe to:
-   - `message.*` (includes edits/deletes/thread broadcasts)
-   - `app_mention`
-   - `reaction_added`, `reaction_removed`
-   - `member_joined_channel`, `member_left_channel`
-   - `channel_rename`
-   - `pin_added`, `pin_removed`
-6. Invite the bot to channels you want it to read.
-7. Slash Commands → create `/openclaw` if you use `channels.slack.slashCommand`. If you enable native commands, add one slash command per built-in command (same names as `/help`). Native defaults to off for Slack unless you set `channels.slack.commands.native: true` (global `commands.native` is `"auto"` which leaves Slack off).
-8. App Home → enable the **Messages Tab** so users can DM the bot.
-
-Use the manifest below so scopes and events stay in sync.
-
-Multi-account support: use `channels.slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
-
-### OpenClaw config (Socket mode)
-
-Set tokens via env vars (recommended):
-
-- `SLACK_APP_TOKEN=xapp-...`
-- `SLACK_BOT_TOKEN=xoxb-...`
-
-Or via config:
-
-```json5
-{
-  channels: {
-    slack: {
-      enabled: true,
-      appToken: "xapp-...",
-      botToken: "xoxb-...",
-    },
-  },
-}
+```bash
+SLACK_APP_TOKEN=xapp-...
+SLACK_BOT_TOKEN=xoxb-...
 ```
 
-### User token (optional)
+      </Step>
 
-OpenClaw can use a Slack user token (`xoxp-...`) for read operations (history,
-pins, reactions, emoji, member info). By default this stays read-only: reads
-prefer the user token when present, and writes still use the bot token unless
-you explicitly opt in. Even with `userTokenReadOnly: false`, the bot token stays
-preferred for writes when it is available.
+      <Step title="Subscribe app events">
+        Subscribe bot events for:
 
-User tokens are configured in the config file (no env var support). For
-multi-account, set `channels.slack.accounts.<id>.userToken`.
+        - `app_mention`
+        - `message.channels`, `message.groups`, `message.im`, `message.mpim`
+        - `reaction_added`, `reaction_removed`
+        - `member_joined_channel`, `member_left_channel`
+        - `channel_rename`
+        - `pin_added`, `pin_removed`
 
-Example with bot + app + user tokens:
+        Also enable App Home **Messages Tab** for DMs.
+      </Step>
 
-```json5
-{
-  channels: {
-    slack: {
-      enabled: true,
-      appToken: "xapp-...",
-      botToken: "xoxb-...",
-      userToken: "xoxp-...",
-    },
-  },
-}
+      <Step title="Start gateway">
+
+```bash
+openclaw gateway
 ```
 
-Example with userTokenReadOnly explicitly set (allow user token writes):
+      </Step>
+    </Steps>
 
-```json5
-{
-  channels: {
-    slack: {
-      enabled: true,
-      appToken: "xapp-...",
-      botToken: "xoxb-...",
-      userToken: "xoxp-...",
-      userTokenReadOnly: false,
-    },
-  },
-}
-```
+  </Tab>
 
-#### Token usage
+  <Tab title="HTTP Events API mode">
+    <Steps>
+      <Step title="Configure Slack app for HTTP">
 
-- Read operations (history, reactions list, pins list, emoji list, member info,
-  search) prefer the user token when configured, otherwise the bot token.
-- Write operations (send/edit/delete messages, add/remove reactions, pin/unpin,
-  file uploads) use the bot token by default. If `userTokenReadOnly: false` and
-  no bot token is available, OpenClaw falls back to the user token.
+        - set mode to HTTP (`channels.slack.mode="http"`)
+        - copy Slack **Signing Secret**
+        - set Event Subscriptions + Interactivity + Slash command Request URL to the same webhook path (default `/slack/events`)
 
-### History context
+      </Step>
 
-- `channels.slack.historyLimit` (or `channels.slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
-- Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
-
-## HTTP mode (Events API)
-
-Use HTTP webhook mode when your Gateway is reachable by Slack over HTTPS (typical for server deployments).
-HTTP mode uses the Events API + Interactivity + Slash Commands with a shared request URL.
-
-### Setup (HTTP mode)
-
-1. Create a Slack app and **disable Socket Mode** (optional if you only use HTTP).
-2. **Basic Information** → copy the **Signing Secret**.
-3. **OAuth & Permissions** → install the app and copy the **Bot User OAuth Token** (`xoxb-...`).
-4. **Event Subscriptions** → enable events and set the **Request URL** to your gateway webhook path (default `/slack/events`).
-5. **Interactivity & Shortcuts** → enable and set the same **Request URL**.
-6. **Slash Commands** → set the same **Request URL** for your command(s).
-
-Example request URL:
-`https://gateway-host/slack/events`
-
-### OpenClaw config (minimal)
+      <Step title="Configure OpenClaw HTTP mode">
 
 ```json5
 {
@@ -158,13 +108,184 @@ Example request URL:
 }
 ```
 
-Multi-account HTTP mode: set `channels.slack.accounts.<id>.mode = "http"` and provide a unique
-`webhookPath` per account so each Slack app can point to its own URL.
+      </Step>
 
-### Manifest (optional)
+      <Step title="Use unique webhook paths for multi-account HTTP">
+        Per-account HTTP mode is supported.
 
-Use this Slack app manifest to create the app quickly (adjust the name/command if you want). Include the
-user scopes if you plan to configure a user token.
+        Give each account a distinct `webhookPath` so registrations do not collide.
+      </Step>
+    </Steps>
+
+  </Tab>
+</Tabs>
+
+## Token model
+
+- `botToken` + `appToken` are required for Socket Mode.
+- HTTP mode requires `botToken` + `signingSecret`.
+- Config tokens override env fallback.
+- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback applies only to the default account.
+- `userToken` (`xoxp-...`) is config-only (no env fallback) and defaults to read-only behavior (`userTokenReadOnly: true`).
+
+<Tip>
+For actions/directory reads, user token can be preferred when configured. For writes, bot token remains preferred; user-token writes are only allowed when `userTokenReadOnly: false` and bot token is unavailable.
+</Tip>
+
+## Access control and routing
+
+<Tabs>
+  <Tab title="DM policy">
+    `channels.slack.dm.policy` controls DM access:
+
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `dm.allowFrom` to include `"*"`)
+    - `disabled`
+
+    DM flags:
+
+    - `dm.enabled` (default true)
+    - `dm.allowFrom`
+    - `dm.groupEnabled` (group DMs default false)
+    - `dm.groupChannels` (optional MPIM allowlist)
+
+    Pairing in DMs uses `openclaw pairing approve slack <code>`.
+
+  </Tab>
+
+  <Tab title="Channel policy">
+    `channels.slack.groupPolicy` controls channel handling:
+
+    - `open`
+    - `allowlist`
+    - `disabled`
+
+    Channel allowlist lives under `channels.slack.channels`.
+
+    Runtime note: if `channels.slack` is completely missing (env-only setup) and `channels.defaults.groupPolicy` is unset, runtime falls back to `groupPolicy="open"` and logs a warning.
+
+    Name/ID resolution:
+
+    - channel allowlist entries and DM allowlist entries are resolved at startup when token access allows
+    - unresolved entries are kept as configured
+
+  </Tab>
+
+  <Tab title="Mentions and channel users">
+    Channel messages are mention-gated by default.
+
+    Mention sources:
+
+    - explicit app mention (`<@botId>`)
+    - mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - implicit reply-to-bot thread behavior
+
+    Per-channel controls (`channels.slack.channels.<id|name>`):
+
+    - `requireMention`
+    - `users` (allowlist)
+    - `allowBots`
+    - `skills`
+    - `systemPrompt`
+    - `tools`, `toolsBySender`
+
+  </Tab>
+</Tabs>
+
+## Commands and slash behavior
+
+- Native command auto-mode is **off** for Slack (`commands.native: "auto"` does not enable Slack native commands).
+- Enable native Slack command handlers with `channels.slack.commands.native: true` (or global `commands.native: true`).
+- When native commands are enabled, register matching slash commands in Slack (`/<command>` names).
+- If native commands are not enabled, you can run a single configured slash command via `channels.slack.slashCommand`.
+
+Default slash command settings:
+
+- `enabled: false`
+- `name: "openclaw"`
+- `sessionPrefix: "slack:slash"`
+- `ephemeral: true`
+
+Slash sessions use isolated keys:
+
+- `agent:<agentId>:slack:slash:<userId>`
+
+and still route command execution against the target conversation session (`CommandTargetSessionKey`).
+
+## Threading, sessions, and reply tags
+
+- DMs route as `direct`; channels as `channel`; MPIMs as `group`.
+- With default `session.dmScope=main`, Slack DMs collapse to agent main session.
+- Channel sessions: `agent:<agentId>:slack:channel:<channelId>`.
+- Thread replies can create thread session suffixes (`:thread:<threadTs>`) when applicable.
+- `channels.slack.thread.historyScope` default is `thread`; `thread.inheritParent` default is `false`.
+
+Reply threading controls:
+
+- `channels.slack.replyToMode`: `off|first|all` (default `off`)
+- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
+- legacy fallback for direct chats: `channels.slack.dm.replyToMode`
+
+Manual reply tags are supported:
+
+- `[[reply_to_current]]`
+- `[[reply_to:<id>]]`
+
+## Media, chunking, and delivery
+
+<AccordionGroup>
+  <Accordion title="Inbound attachments">
+    Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit.
+
+    Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.
+
+  </Accordion>
+
+  <Accordion title="Outbound text and files">
+    - text chunks use `channels.slack.textChunkLimit` (default 4000)
+    - `channels.slack.chunkMode="newline"` enables paragraph-first splitting
+    - file sends use Slack upload APIs and can include thread replies (`thread_ts`)
+    - outbound media cap follows `channels.slack.mediaMaxMb` when configured; otherwise channel sends use MIME-kind defaults from media pipeline
+  </Accordion>
+
+  <Accordion title="Delivery targets">
+    Preferred explicit targets:
+
+    - `user:<id>` for DMs
+    - `channel:<id>` for channels
+
+    Slack DMs are opened via Slack conversation APIs when sending to user targets.
+
+  </Accordion>
+</AccordionGroup>
+
+## Actions and gates
+
+Slack actions are controlled by `channels.slack.actions.*`.
+
+Available action groups in current Slack tooling:
+
+| Group      | Default |
+| ---------- | ------- |
+| messages   | enabled |
+| reactions  | enabled |
+| pins       | enabled |
+| memberInfo | enabled |
+| emojiList  | enabled |
+
+## Events and operational behavior
+
+- Message edits/deletes/thread broadcasts are mapped into system events.
+- Reaction add/remove events are mapped into system events.
+- Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
+- `channel_id_changed` can migrate channel config keys when `configWrites` is enabled.
+- Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
+
+## Manifest and scope checklist
+
+<AccordionGroup>
+  <Accordion title="Slack app manifest example">
 
 ```json
 {
@@ -196,14 +317,8 @@ user scopes if you plan to configure a user token.
         "channels:history",
         "channels:read",
         "groups:history",
-        "groups:read",
-        "groups:write",
         "im:history",
-        "im:read",
-        "im:write",
         "mpim:history",
-        "mpim:read",
-        "mpim:write",
         "users:read",
         "app_mentions:read",
         "reactions:read",
@@ -214,21 +329,6 @@ user scopes if you plan to configure a user token.
         "commands",
         "files:read",
         "files:write"
-      ],
-      "user": [
-        "channels:history",
-        "channels:read",
-        "groups:history",
-        "groups:read",
-        "im:history",
-        "im:read",
-        "mpim:history",
-        "mpim:read",
-        "users:read",
-        "reactions:read",
-        "pins:read",
-        "emoji:read",
-        "search:read"
       ]
     }
   },
@@ -254,321 +354,100 @@ user scopes if you plan to configure a user token.
 }
 ```
 
-If you enable native commands, add one `slash_commands` entry per command you want to expose (matching the `/help` list). Override with `channels.slack.commands.native`.
+  </Accordion>
 
-## Scopes (current vs optional)
+  <Accordion title="Optional user-token scopes (read operations)">
+    If you configure `channels.slack.userToken`, typical read scopes are:
 
-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/](https://docs.slack.dev/apis/web-api/using-the-conversations-api/) for the overview.
+    - `channels:history`, `groups:history`, `im:history`, `mpim:history`
+    - `channels:read`, `groups:read`, `im:read`, `mpim:read`
+    - `users:read`
+    - `reactions:read`
+    - `pins:read`
+    - `emoji:read`
+    - `search:read` (if you depend on Slack search reads)
 
-### 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)
-- `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)
-- `channels:history`, `groups:history`, `im:history`, `mpim: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)
-- `users:read` (user lookup)
-  [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.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.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)
-- `files:write` (uploads via `files.uploadV2`)
-  [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)
-
-Add these under **User Token Scopes** if you configure `channels.slack.userToken`.
-
-- `channels:history`, `groups:history`, `im:history`, `mpim:history`
-- `channels:read`, `groups:read`, `im:read`, `mpim:read`
-- `users:read`
-- `reactions:read`
-- `pins:read`
-- `emoji:read`
-- `search:read`
-
-### Not needed today (but likely future)
-
-- `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)
-- `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)
-- `files:read` (only if we start listing/reading file metadata)
-
-## Config
-
-Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
-
-```json
-{
-  "slack": {
-    "enabled": true,
-    "botToken": "xoxb-...",
-    "appToken": "xapp-...",
-    "groupPolicy": "allowlist",
-    "dm": {
-      "enabled": true,
-      "policy": "pairing",
-      "allowFrom": ["U123", "U456", "*"],
-      "groupEnabled": false,
-      "groupChannels": ["G123"],
-      "replyToMode": "all"
-    },
-    "channels": {
-      "C123": { "allow": true, "requireMention": true },
-      "#general": {
-        "allow": true,
-        "requireMention": true,
-        "users": ["U123"],
-        "skills": ["search", "docs"],
-        "systemPrompt": "Keep answers short."
-      }
-    },
-    "reactionNotifications": "own",
-    "reactionAllowlist": ["U123"],
-    "replyToMode": "off",
-    "actions": {
-      "reactions": true,
-      "messages": true,
-      "pins": true,
-      "memberInfo": true,
-      "emojiList": true
-    },
-    "slashCommand": {
-      "enabled": true,
-      "name": "openclaw",
-      "sessionPrefix": "slack:slash",
-      "ephemeral": true
-    },
-    "textChunkLimit": 4000,
-    "mediaMaxMb": 20
-  }
-}
-```
-
-Tokens can also be supplied via env vars:
-
-- `SLACK_BOT_TOKEN`
-- `SLACK_APP_TOKEN`
-
-Ack reactions are controlled globally via `messages.ackReaction` +
-`messages.ackReactionScope`. Use `messages.removeAckAfterReply` to clear the
-ack reaction after the bot replies.
-
-## Limits
-
-- Outbound text is chunked to `channels.slack.textChunkLimit` (default 4000).
-- Optional newline chunking: set `channels.slack.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking.
-- Media uploads are capped by `channels.slack.mediaMaxMb` (default 20).
-
-## Reply threading
-
-By default, OpenClaw replies in the main channel. Use `channels.slack.replyToMode` to control automatic threading:
-
-| Mode    | Behavior                                                                                                                                                            |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `off`   | **Default.** Reply in main channel. Only thread if the triggering message was already in a thread.                                                                  |
-| `first` | First reply goes to thread (under the triggering message), subsequent replies go to main channel. Useful for keeping context visible while avoiding thread clutter. |
-| `all`   | All replies go to thread. Keeps conversations contained but may reduce visibility.                                                                                  |
-
-The mode applies to both auto-replies and agent tool calls (`slack sendMessage`).
-
-### Per-chat-type threading
-
-You can configure different threading behavior per chat type by setting `channels.slack.replyToModeByChatType`:
-
-```json5
-{
-  channels: {
-    slack: {
-      replyToMode: "off", // default for channels
-      replyToModeByChatType: {
-        direct: "all", // DMs always thread
-        group: "first", // group DMs/MPIM thread first reply
-      },
-    },
-  },
-}
-```
-
-Supported chat types:
-
-- `direct`: 1:1 DMs (Slack `im`)
-- `group`: group DMs / MPIMs (Slack `mpim`)
-- `channel`: standard channels (public/private)
-
-Precedence:
-
-1. `replyToModeByChatType.<chatType>`
-2. `replyToMode`
-3. Provider default (`off`)
-
-Legacy `channels.slack.dm.replyToMode` is still accepted as a fallback for `direct` when no chat-type override is set.
-
-Examples:
-
-Thread DMs only:
-
-```json5
-{
-  channels: {
-    slack: {
-      replyToMode: "off",
-      replyToModeByChatType: { direct: "all" },
-    },
-  },
-}
-```
-
-Thread group DMs but keep channels in the root:
-
-```json5
-{
-  channels: {
-    slack: {
-      replyToMode: "off",
-      replyToModeByChatType: { group: "first" },
-    },
-  },
-}
-```
-
-Make channels thread, keep DMs in the root:
-
-```json5
-{
-  channels: {
-    slack: {
-      replyToMode: "first",
-      replyToModeByChatType: { direct: "off", group: "off" },
-    },
-  },
-}
-```
-
-### Manual threading tags
-
-For fine-grained control, use these tags in agent responses:
-
-- `[[reply_to_current]]` — reply to the triggering message (start/continue thread).
-- `[[reply_to:<id>]]` — reply to a specific message id.
-
-## Sessions + routing
-
-- DMs share the `main` session (like WhatsApp/Telegram).
-- Channels map to `agent:<agentId>:slack:channel:<channelId>` sessions.
-- Slash commands use `agent:<agentId>:slack:slash:<userId>` sessions (prefix configurable via `channels.slack.slashCommand.sessionPrefix`).
-- If Slack doesn’t provide `channel_type`, OpenClaw infers it from the channel ID prefix (`D`, `C`, `G`) and defaults to `channel` to keep session keys stable.
-- Native command registration uses `commands.native` (global default `"auto"` → Slack off) and can be overridden per-workspace with `channels.slack.commands.native`. Text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
-- Full command list + config: [Slash commands](/tools/slash-commands)
-
-## DM security (pairing)
-
-- Default: `channels.slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
-- Approve via: `openclaw pairing approve slack <code>`.
-- To allow anyone: set `channels.slack.dm.policy="open"` and `channels.slack.dm.allowFrom=["*"]`.
-- `channels.slack.dm.allowFrom` accepts user IDs, @handles, or emails (resolved at startup when tokens allow). The wizard accepts usernames and resolves them to ids during setup when tokens allow.
-
-## Group policy
-
-- `channels.slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
-- `allowlist` requires channels to be listed in `channels.slack.channels`.
-- If you only set `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` and never create a `channels.slack` section,
-  the runtime defaults `groupPolicy` to `open`. Add `channels.slack.groupPolicy`,
-  `channels.defaults.groupPolicy`, or a channel allowlist to lock it down.
-- The configure wizard accepts `#channel` names and resolves them to IDs when possible
-  (public + private); if multiple matches exist, it prefers the active channel.
-- On startup, OpenClaw resolves channel/user names in allowlists to IDs (when tokens allow)
-  and logs the mapping; unresolved entries are kept as typed.
-- To allow **no channels**, set `channels.slack.groupPolicy: "disabled"` (or keep an empty allowlist).
-
-Channel options (`channels.slack.channels.<id>` or `channels.slack.channels.<name>`):
-
-- `allow`: allow/deny the channel when `groupPolicy="allowlist"`.
-- `requireMention`: mention gating for the channel.
-- `tools`: optional per-channel tool policy overrides (`allow`/`deny`/`alsoAllow`).
-- `toolsBySender`: optional per-sender tool policy overrides within the channel (keys are sender ids/@handles/emails; `"*"` wildcard supported).
-- `allowBots`: allow bot-authored messages in this channel (default: false).
-- `users`: optional per-channel user allowlist.
-- `skills`: skill filter (omit = all skills, empty = none).
-- `systemPrompt`: extra system prompt for the channel (combined with topic/purpose).
-- `enabled`: set `false` to disable the channel.
-
-## Delivery targets
-
-Use these with cron/CLI sends:
-
-- `user:<id>` for DMs
-- `channel:<id>` for channels
-
-## Tool actions
-
-Slack tool actions can be gated with `channels.slack.actions.*`:
-
-| Action group | Default | Notes                  |
-| ------------ | ------- | ---------------------- |
-| reactions    | enabled | React + list reactions |
-| messages     | enabled | Read/send/edit/delete  |
-| pins         | enabled | Pin/unpin/list         |
-| memberInfo   | enabled | Member info            |
-| emojiList    | enabled | Custom emoji list      |
-
-## Security notes
-
-- Writes default to the bot token so state-changing actions stay scoped to the
-  app's bot permissions and identity.
-- Setting `userTokenReadOnly: false` allows the user token to be used for write
-  operations when a bot token is unavailable, which means actions run with the
-  installing user's access. Treat the user token as highly privileged and keep
-  action gates and allowlists tight.
-- If you enable user-token writes, make sure the user token includes the write
-  scopes you expect (`chat:write`, `reactions:write`, `pins:write`,
-  `files:write`) or those operations will fail.
+  </Accordion>
+</AccordionGroup>
 
 ## Troubleshooting
 
-Run this ladder first:
+<AccordionGroup>
+  <Accordion title="No replies in channels">
+    Check, in order:
+
+    - `groupPolicy`
+    - channel allowlist (`channels.slack.channels`)
+    - `requireMention`
+    - per-channel `users` allowlist
+
+    Useful commands:
 
 ```bash
-openclaw status
-openclaw gateway status
+openclaw channels status --probe
 openclaw logs --follow
 openclaw doctor
-openclaw channels status --probe
 ```
 
-Then confirm DM pairing state if needed:
+  </Accordion>
+
+  <Accordion title="DM messages ignored">
+    Check:
+
+    - `channels.slack.dm.enabled`
+    - `channels.slack.dm.policy`
+    - pairing approvals / allowlist entries
 
 ```bash
 openclaw pairing list slack
 ```
 
-Common failures:
+  </Accordion>
 
-- 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.
+  <Accordion title="Socket mode not connecting">
+    Validate bot + app tokens and Socket Mode enablement in Slack app settings.
+  </Accordion>
 
-For triage flow: [/channels/troubleshooting](/channels/troubleshooting).
+  <Accordion title="HTTP mode not receiving events">
+    Validate:
 
-## Notes
+    - signing secret
+    - webhook path
+    - Slack Request URLs (Events + Interactivity + Slash Commands)
+    - unique `webhookPath` per HTTP account
 
-- Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.
-- Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
-- Reaction notifications follow `channels.slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
-- Bot-authored messages are ignored by default; enable via `channels.slack.allowBots` or `channels.slack.channels.<id>.allowBots`.
-- Warning: If you allow replies to other bots (`channels.slack.allowBots=true` or `channels.slack.channels.<id>.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.slack.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
-- For the Slack tool, reaction removal semantics are in [/tools/reactions](/tools/reactions).
-- Attachments are downloaded to the media store when permitted and under the size limit.
+  </Accordion>
+
+  <Accordion title="Native/slash commands not firing">
+    Verify whether you intended:
+
+    - native command mode (`channels.slack.commands.native: true`) with matching slash commands registered in Slack
+    - or single slash command mode (`channels.slack.slashCommand.enabled: true`)
+
+    Also check `commands.useAccessGroups` and channel/user allowlists.
+
+  </Accordion>
+</AccordionGroup>
+
+## Configuration reference pointers
+
+Primary reference:
+
+- [Configuration reference - Slack](/gateway/configuration-reference#slack)
+
+High-signal Slack fields:
+
+- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
+- DM access: `dm.enabled`, `dm.policy`, `dm.allowFrom`, `dm.groupEnabled`, `dm.groupChannels`
+- channel access: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
+- threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
+- delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`
+- ops/features: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
+
+## Related
+
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Troubleshooting](/channels/troubleshooting)
+- [Configuration](/gateway/configuration)
+- [Slash commands](/tools/slash-commands)

docs/channels/whatsapp.md

@@ -1,406 +1,434 @@
 ---
-summary: "WhatsApp (web channel) integration: login, inbox, replies, media, and ops"
+summary: "WhatsApp channel support, access controls, delivery behavior, and operations"
 read_when:
   - Working on WhatsApp/web channel behavior or inbox routing
 title: "WhatsApp"
 ---
 
-# WhatsApp (web channel)
+# WhatsApp (Web channel)
 
-Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
+Status: production-ready via WhatsApp Web (Baileys). Gateway owns linked session(s).
 
-## Quick setup (beginner)
+<CardGroup cols={3}>
+  <Card title="Pairing" icon="link" href="/channels/pairing">
+    Default DM policy is pairing for unknown senders.
+  </Card>
+  <Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
+    Cross-channel diagnostics and repair playbooks.
+  </Card>
+  <Card title="Gateway configuration" icon="settings" href="/gateway/configuration">
+    Full channel config patterns and examples.
+  </Card>
+</CardGroup>
 
-1. Use a **separate phone number** if possible (recommended).
-2. Configure WhatsApp in `~/.openclaw/openclaw.json`.
-3. Run `openclaw channels login` to scan the QR code (Linked Devices).
-4. Start the gateway.
+## Quick setup
 
-Minimal config:
+<Steps>
+  <Step title="Configure WhatsApp access policy">
 
 ```json5
 {
   channels: {
     whatsapp: {
-      dmPolicy: "allowlist",
+      dmPolicy: "pairing",
       allowFrom: ["+15551234567"],
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15551234567"],
     },
   },
 }
 ```
 
-## Goals
+  </Step>
 
-- Multiple WhatsApp accounts (multi-account) in one Gateway process.
-- Deterministic routing: replies return to WhatsApp, no model routing.
-- Model sees enough context to understand quoted replies.
+  <Step title="Link WhatsApp (QR)">
 
-## Config writes
-
-By default, WhatsApp is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
-
-Disable with:
-
-```json5
-{
-  channels: { whatsapp: { configWrites: false } },
-}
+```bash
+openclaw channels login --channel whatsapp
 ```
 
-## Architecture (who owns what)
+    For a specific account:
 
-- **Gateway** owns the Baileys socket and inbox loop.
-- **CLI / macOS app** talk to the gateway; no direct Baileys use.
-- **Active listener** is required for outbound sends; otherwise send fails fast.
+```bash
+openclaw channels login --channel whatsapp --account work
+```
 
-## Getting a phone number (two modes)
+  </Step>
 
-WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked. There are two supported ways to run OpenClaw on WhatsApp:
+  <Step title="Start the gateway">
 
-### Dedicated number (recommended)
+```bash
+openclaw gateway
+```
 
-Use a **separate phone number** for OpenClaw. Best UX, clean routing, no self-chat quirks. Ideal setup: **spare/old Android phone + eSIM**. Leave it on Wi‑Fi and power, and link it via QR.
+  </Step>
 
-**WhatsApp Business:** You can use WhatsApp Business on the same device with a different number. Great for keeping your personal WhatsApp separate — install WhatsApp Business and register the OpenClaw number there.
+  <Step title="Approve first pairing request (if using pairing mode)">
 
-**Sample config (dedicated number, single-user allowlist):**
+```bash
+openclaw pairing list whatsapp
+openclaw pairing approve whatsapp <CODE>
+```
+
+    Pairing requests expire after 1 hour. Pending requests are capped at 3 per channel.
+
+  </Step>
+</Steps>
+
+<Note>
+OpenClaw recommends running WhatsApp on a separate number when possible. (The channel metadata and onboarding flow are optimized for that setup, but personal-number setups are also supported.)
+</Note>
+
+## Deployment patterns
+
+<AccordionGroup>
+  <Accordion title="Dedicated number (recommended)">
+    This is the cleanest operational mode:
+
+    - separate WhatsApp identity for OpenClaw
+    - clearer DM allowlists and routing boundaries
+    - lower chance of self-chat confusion
+
+    Minimal policy pattern:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          dmPolicy: "allowlist",
+          allowFrom: ["+15551234567"],
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Personal-number fallback">
+    Onboarding supports personal-number mode and writes a self-chat-friendly baseline:
+
+    - `dmPolicy: "allowlist"`
+    - `allowFrom` includes your personal number
+    - `selfChatMode: true`
+
+    In runtime, self-chat protections key off the linked self number and `allowFrom`.
+
+  </Accordion>
+
+  <Accordion title="WhatsApp Web-only channel scope">
+    The messaging platform channel is WhatsApp Web-based (`Baileys`) in current OpenClaw channel architecture.
+
+    There is no separate Twilio WhatsApp messaging channel in the built-in chat-channel registry.
+
+  </Accordion>
+</AccordionGroup>
+
+## Runtime model
+
+- Gateway owns the WhatsApp socket and reconnect loop.
+- Outbound sends require an active WhatsApp listener for the target account.
+- Status and broadcast chats are ignored (`@status`, `@broadcast`).
+- Direct chats use DM session rules (`session.dmScope`; default `main` collapses DMs to the agent main session).
+- Group sessions are isolated (`agent:<agentId>:whatsapp:group:<jid>`).
+
+## Access control and activation
+
+<Tabs>
+  <Tab title="DM policy">
+    `channels.whatsapp.dmPolicy` controls direct chat access:
+
+    - `pairing` (default)
+    - `allowlist`
+    - `open` (requires `allowFrom` to include `"*"`)
+    - `disabled`
+
+    `allowFrom` accepts E.164-style numbers (normalized internally).
+
+    Runtime behavior details:
+
+    - pairings are persisted in channel allow-store and merged with configured `allowFrom`
+    - if no allowlist is configured, the linked self number is allowed by default
+    - outbound `fromMe` DMs are never auto-paired
+
+  </Tab>
+
+  <Tab title="Group policy + allowlists">
+    Group access has two layers:
+
+    1. **Group membership allowlist** (`channels.whatsapp.groups`)
+       - if `groups` is omitted, all groups are eligible
+       - if `groups` is present, it acts as a group allowlist (`"*"` allowed)
+
+    2. **Group sender policy** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
+       - `open`: sender allowlist bypassed
+       - `allowlist`: sender must match `groupAllowFrom` (or `*`)
+       - `disabled`: block all group inbound
+
+    Sender allowlist fallback:
+
+    - if `groupAllowFrom` is unset, runtime falls back to `allowFrom` when available
+
+    Note: if no `channels.whatsapp` block exists at all, runtime group-policy fallback is effectively `open`.
+
+  </Tab>
+
+  <Tab title="Mentions + /activation">
+    Group replies require mention by default.
+
+    Mention detection includes:
+
+    - explicit WhatsApp mentions of the bot identity
+    - configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
+    - implicit reply-to-bot detection (reply sender matches bot identity)
+
+    Session-level activation command:
+
+    - `/activation mention`
+    - `/activation always`
+
+    `activation` updates session state (not global config). It is owner-gated.
+
+  </Tab>
+</Tabs>
+
+## Personal-number and self-chat behavior
+
+When the linked self number is also present in `allowFrom`, WhatsApp self-chat safeguards activate:
+
+- skip read receipts for self-chat turns
+- ignore mention-JID auto-trigger behavior that would otherwise ping yourself
+- if `messages.responsePrefix` is unset, self-chat replies default to `[{identity.name}]` or `[openclaw]`
+
+## Message normalization and context
+
+<AccordionGroup>
+  <Accordion title="Inbound envelope + reply context">
+    Incoming WhatsApp messages are wrapped in the shared inbound envelope.
+
+    If a quoted reply exists, context is appended in this form:
+
+    ```text
+    [Replying to <sender> id:<stanzaId>]
+    <quoted body or media placeholder>
+    [/Replying]
+    ```
+
+    Reply metadata fields are also populated when available (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
+
+  </Accordion>
+
+  <Accordion title="Media placeholders and location/contact extraction">
+    Media-only inbound messages are normalized with placeholders such as:
+
+    - `<media:image>`
+    - `<media:video>`
+    - `<media:audio>`
+    - `<media:document>`
+    - `<media:sticker>`
+
+    Location and contact payloads are normalized into textual context before routing.
+
+  </Accordion>
+
+  <Accordion title="Pending group history injection">
+    For groups, unprocessed messages can be buffered and injected as context when the bot is finally triggered.
+
+    - default limit: `50`
+    - config: `channels.whatsapp.historyLimit`
+    - fallback: `messages.groupChat.historyLimit`
+    - `0` disables
+
+    Injection markers:
+
+    - `[Chat messages since your last reply - for context]`
+    - `[Current message - respond to this]`
+
+  </Accordion>
+
+  <Accordion title="Read receipts">
+    Read receipts are enabled by default for accepted inbound WhatsApp messages.
+
+    Disable globally:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          sendReadReceipts: false,
+        },
+      },
+    }
+    ```
+
+    Per-account override:
+
+    ```json5
+    {
+      channels: {
+        whatsapp: {
+          accounts: {
+            work: {
+              sendReadReceipts: false,
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    Self-chat turns skip read receipts even when globally enabled.
+
+  </Accordion>
+</AccordionGroup>
+
+## Delivery, chunking, and media
+
+<AccordionGroup>
+  <Accordion title="Text chunking">
+    - default chunk limit: `channels.whatsapp.textChunkLimit = 4000`
+    - `channels.whatsapp.chunkMode = "length" | "newline"`
+    - `newline` mode prefers paragraph boundaries (blank lines), then falls back to length-safe chunking
+  </Accordion>
+
+  <Accordion title="Outbound media behavior">
+    - supports image, video, audio (PTT voice-note), and document payloads
+    - `audio/ogg` is rewritten to `audio/ogg; codecs=opus` for voice-note compatibility
+    - animated GIF playback is supported via `gifPlayback: true` on video sends
+    - captions are applied to the first media item when sending multi-media reply payloads
+    - media source can be HTTP(S), `file://`, or local paths
+  </Accordion>
+
+  <Accordion title="Media size limits and fallback behavior">
+    - inbound media save cap: `channels.whatsapp.mediaMaxMb` (default `50`)
+    - outbound media cap for auto-replies: `agents.defaults.mediaMaxMb` (default `5MB`)
+    - images are auto-optimized (resize/quality sweep) to fit limits
+    - on media send failure, first-item fallback sends text warning instead of dropping the response silently
+  </Accordion>
+</AccordionGroup>
+
+## Acknowledgment reactions
+
+WhatsApp supports immediate ack reactions on inbound receipt via `channels.whatsapp.ackReaction`.
 
 ```json5
 {
   channels: {
     whatsapp: {
-      dmPolicy: "allowlist",
-      allowFrom: ["+15551234567"],
-    },
-  },
-}
-```
-
-**Pairing mode (optional):**
-If you want pairing instead of allowlist, set `channels.whatsapp.dmPolicy` to `pairing`. Unknown senders get a pairing code; approve with:
-`openclaw pairing approve whatsapp <code>`
-
-### Personal number (fallback)
-
-Quick fallback: run OpenClaw on **your own number**. Message yourself (WhatsApp “Message yourself”) for testing so you don’t spam contacts. Expect to read verification codes on your main phone during setup and experiments. **Must enable self-chat mode.**
-When the wizard asks for your personal WhatsApp number, enter the phone you will message from (the owner/sender), not the assistant number.
-
-**Sample config (personal number, self-chat):**
-
-```json
-{
-  "whatsapp": {
-    "selfChatMode": true,
-    "dmPolicy": "allowlist",
-    "allowFrom": ["+15551234567"]
-  }
-}
-```
-
-Self-chat replies default to `[{identity.name}]` when set (otherwise `[openclaw]`)
-if `messages.responsePrefix` is unset. Set it explicitly to customize or disable
-the prefix (use `""` to remove it).
-
-### Number sourcing tips
-
-- **Local eSIM** from your country's mobile carrier (most reliable)
-  - Austria: [hot.at](https://www.hot.at)
-  - UK: [giffgaff](https://www.giffgaff.com) — free SIM, no contract
-- **Prepaid SIM** — cheap, just needs to receive one SMS for verification
-
-**Avoid:** TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively.
-
-**Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
-
-## Why Not Twilio?
-
-- Early OpenClaw builds supported Twilio’s WhatsApp Business integration.
-- WhatsApp Business numbers are a poor fit for a personal assistant.
-- Meta enforces a 24‑hour reply window; if you haven’t responded in the last 24 hours, the business number can’t initiate new messages.
-- High-volume or “chatty” usage triggers aggressive blocking, because business accounts aren’t meant to send dozens of personal assistant messages.
-- Result: unreliable delivery and frequent blocks, so support was removed.
-
-## Login + credentials
-
-- Login command: `openclaw channels login` (QR via Linked Devices).
-- Multi-account login: `openclaw channels login --account <id>` (`<id>` = `accountId`).
-- Default account (when `--account` is omitted): `default` if present, otherwise the first configured account id (sorted).
-- Credentials stored in `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`.
-- Backup copy at `creds.json.bak` (restored on corruption).
-- Legacy compatibility: older installs stored Baileys files directly in `~/.openclaw/credentials/`.
-- Logout: `openclaw channels logout` (or `--account <id>`) deletes WhatsApp auth state (but keeps shared `oauth.json`).
-- Logged-out socket => error instructs re-link.
-
-## Inbound flow (DM + group)
-
-- WhatsApp events come from `messages.upsert` (Baileys).
-- Inbox listeners are detached on shutdown to avoid accumulating event handlers in tests/restarts.
-- Status/broadcast chats are ignored.
-- Direct chats use E.164; groups use group JID.
-- **DM policy**: `channels.whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
-  - Pairing: unknown senders get a pairing code (approve via `openclaw pairing approve whatsapp <code>`; codes expire after 1 hour).
-  - Open: requires `channels.whatsapp.allowFrom` to include `"*"`.
-  - Your linked WhatsApp number is implicitly trusted, so self messages skip ⁠`channels.whatsapp.dmPolicy` and `channels.whatsapp.allowFrom` checks.
-
-### Personal-number mode (fallback)
-
-If you run OpenClaw on your **personal WhatsApp number**, enable `channels.whatsapp.selfChatMode` (see sample above).
-
-Behavior:
-
-- Outbound DMs never trigger pairing replies (prevents spamming contacts).
-- Inbound unknown senders still follow `channels.whatsapp.dmPolicy`.
-- Self-chat mode (allowFrom includes your number) avoids auto read receipts and ignores mention JIDs.
-- Read receipts sent for non-self-chat DMs.
-
-## Read receipts
-
-By default, the gateway marks inbound WhatsApp messages as read (blue ticks) once they are accepted.
-
-Disable globally:
-
-```json5
-{
-  channels: { whatsapp: { sendReadReceipts: false } },
-}
-```
-
-Disable per account:
-
-```json5
-{
-  channels: {
-    whatsapp: {
-      accounts: {
-        personal: { sendReadReceipts: false },
+      ackReaction: {
+        emoji: "👀",
+        direct: true,
+        group: "mentions", // always | mentions | never
       },
     },
   },
 }
 ```
 
-Notes:
+Behavior notes:
 
-- Self-chat mode always skips read receipts.
+- sent immediately after inbound is accepted (pre-reply)
+- failures are logged but do not block normal reply delivery
+- group mode `mentions` reacts on mention-triggered turns; group activation `always` acts as bypass for this check
+- WhatsApp uses `channels.whatsapp.ackReaction` (legacy `messages.ackReaction` is not used here)
 
-## WhatsApp FAQ: sending messages + pairing
+## Multi-account and credentials
 
-**Will OpenClaw message random contacts when I link WhatsApp?**  
-No. Default DM policy is **pairing**, so unknown senders only get a pairing code and their message is **not processed**. OpenClaw only replies to chats it receives, or to sends you explicitly trigger (agent/CLI).
+<AccordionGroup>
+  <Accordion title="Account selection and defaults">
+    - account ids come from `channels.whatsapp.accounts`
+    - default account selection: `default` if present, otherwise first configured account id (sorted)
+    - account ids are normalized internally for lookup
+  </Accordion>
 
-**How does pairing work on WhatsApp?**  
-Pairing is a DM gate for unknown senders:
+  <Accordion title="Credential paths and legacy compatibility">
+    - current auth path: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
+    - backup file: `creds.json.bak`
+    - legacy default auth in `~/.openclaw/credentials/` is still recognized/migrated for default-account flows
+  </Accordion>
 
-- First DM from a new sender returns a short code (message is not processed).
-- Approve with: `openclaw pairing approve whatsapp <code>` (list with `openclaw pairing list whatsapp`).
-- Codes expire after 1 hour; pending requests are capped at 3 per channel.
+  <Accordion title="Logout behavior">
+    `openclaw channels logout --channel whatsapp [--account <id>]` clears WhatsApp auth state for that account.
 
-**Can multiple people use different OpenClaw instances on one WhatsApp number?**  
-Yes, by routing each sender to a different agent via `bindings` (peer `kind: "direct"`, sender E.164 like `+15551234567`). Replies still come from the **same WhatsApp account**, and direct chats collapse to each agent's main session, so use **one agent per person**. DM access control (`dmPolicy`/`allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent).
+    In legacy auth directories, `oauth.json` is preserved while Baileys auth files are removed.
 
-**Why do you ask for my phone number in the wizard?**  
-The wizard uses it to set your **allowlist/owner** so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that same number and enable `channels.whatsapp.selfChatMode`.
+  </Accordion>
+</AccordionGroup>
 
-## Message normalization (what the model sees)
+## Tools, actions, and config writes
 
-- `Body` is the current message body with envelope.
-- Quoted reply context is **always appended**:
+- Agent tool support includes WhatsApp reaction action (`react`).
+- Action gates:
+  - `channels.whatsapp.actions.reactions`
+  - `channels.whatsapp.actions.polls`
+- Channel-initiated config writes are enabled by default (disable via `channels.whatsapp.configWrites=false`).
 
-  ```
-  [Replying to +1555 id:ABC123]
-  <quoted text or <media:...>>
-  [/Replying]
-  ```
+## Troubleshooting
 
-- Reply metadata also set:
-  - `ReplyToId` = stanzaId
-  - `ReplyToBody` = quoted body or media placeholder
-  - `ReplyToSender` = E.164 when known
-- Media-only inbound messages use placeholders:
-  - `<media:image|video|audio|document|sticker>`
+<AccordionGroup>
+  <Accordion title="Not linked (QR required)">
+    Symptom: channel status reports not linked.
 
-## Groups
+    Fix:
 
-- Groups map to `agent:<agentId>:whatsapp:group:<jid>` sessions.
-- Group policy: `channels.whatsapp.groupPolicy = open|disabled|allowlist` (default `allowlist`).
-- Activation modes:
-  - `mention` (default): requires @mention or regex match.
-  - `always`: always triggers.
-- `/activation mention|always` is owner-only and must be sent as a standalone message.
-- Owner = `channels.whatsapp.allowFrom` (or self E.164 if unset).
-- **History injection** (pending-only):
-  - Recent _unprocessed_ messages (default 50) inserted under:
-    `[Chat messages since your last reply - for context]` (messages already in the session are not re-injected)
-  - Current message under:
-    `[Current message - respond to this]`
-  - Sender suffix appended: `[from: Name (+E164)]`
-- Group metadata cached 5 min (subject + participants).
+    ```bash
+    openclaw channels login --channel whatsapp
+    openclaw channels status
+    ```
 
-## Reply delivery (threading)
+  </Accordion>
 
-- WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
-- Reply tags are ignored on this channel.
+  <Accordion title="Linked but disconnected / reconnect loop">
+    Symptom: linked account with repeated disconnects or reconnect attempts.
 
-## Acknowledgment reactions (auto-react on receipt)
+    Fix:
 
-WhatsApp can automatically send emoji reactions to incoming messages immediately upon receipt, before the bot generates a reply. This provides instant feedback to users that their message was received.
+    ```bash
+    openclaw doctor
+    openclaw logs --follow
+    ```
 
-**Configuration:**
+    If needed, re-link with `channels login`.
 
-```json
-{
-  "whatsapp": {
-    "ackReaction": {
-      "emoji": "👀",
-      "direct": true,
-      "group": "mentions"
-    }
-  }
-}
-```
+  </Accordion>
 
-**Options:**
+  <Accordion title="No active listener when sending">
+    Outbound sends fail fast when no active gateway listener exists for the target account.
 
-- `emoji` (string): Emoji to use for acknowledgment (e.g., "👀", "✅", "📨"). Empty or omitted = feature disabled.
-- `direct` (boolean, default: `true`): Send reactions in direct/DM chats.
-- `group` (string, default: `"mentions"`): Group chat behavior:
-  - `"always"`: React to all group messages (even without @mention)
-  - `"mentions"`: React only when bot is @mentioned
-  - `"never"`: Never react in groups
+    Make sure gateway is running and the account is linked.
 
-**Per-account override:**
+  </Accordion>
 
-```json
-{
-  "whatsapp": {
-    "accounts": {
-      "work": {
-        "ackReaction": {
-          "emoji": "✅",
-          "direct": false,
-          "group": "always"
-        }
-      }
-    }
-  }
-}
-```
+  <Accordion title="Group messages unexpectedly ignored">
+    Check in this order:
 
-**Behavior notes:**
+    - `groupPolicy`
+    - `groupAllowFrom` / `allowFrom`
+    - `groups` allowlist entries
+    - mention gating (`requireMention` + mention patterns)
 
-- Reactions are sent **immediately** upon message receipt, before typing indicators or bot replies.
-- In groups with `requireMention: false` (activation: always), `group: "mentions"` will react to all messages (not just @mentions).
-- Fire-and-forget: reaction failures are logged but don't prevent the bot from replying.
-- Participant JID is automatically included for group reactions.
-- WhatsApp ignores `messages.ackReaction`; use `channels.whatsapp.ackReaction` instead.
+  </Accordion>
 
-## Agent tool (reactions)
+  <Accordion title="Bun runtime warning">
+    WhatsApp gateway runtime should use Node. Bun is flagged as incompatible for stable WhatsApp/Telegram gateway operation.
+  </Accordion>
+</AccordionGroup>
 
-- Tool: `whatsapp` with `react` action (`chatJid`, `messageId`, `emoji`, optional `remove`).
-- Optional: `participant` (group sender), `fromMe` (reacting to your own message), `accountId` (multi-account).
-- Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-- Tool gating: `channels.whatsapp.actions.reactions` (default: enabled).
+## Configuration reference pointers
 
-## Limits
+Primary reference:
 
-- Outbound text is chunked to `channels.whatsapp.textChunkLimit` (default 4000).
-- Optional newline chunking: set `channels.whatsapp.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking.
-- Inbound media saves are capped by `channels.whatsapp.mediaMaxMb` (default 50 MB).
-- Outbound media items are capped by `agents.defaults.mediaMaxMb` (default 5 MB).
+- [Configuration reference - WhatsApp](/gateway/configuration-reference#whatsapp)
 
-## Outbound send (text + media)
+High-signal WhatsApp fields:
 
-- Uses active web listener; error if gateway not running.
-- Text chunking: 4k max per message (configurable via `channels.whatsapp.textChunkLimit`, optional `channels.whatsapp.chunkMode`).
-- Media:
-  - Image/video/audio/document supported.
-  - Audio sent as PTT; `audio/ogg` => `audio/ogg; codecs=opus`.
-  - Caption only on first media item.
-  - Media fetch supports HTTP(S) and local paths.
-  - Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
-    - CLI: `openclaw message send --media <mp4> --gif-playback`
-    - Gateway: `send` params include `gifPlayback: true`
+- access: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
+- delivery: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`
+- multi-account: `accounts.<id>.enabled`, `accounts.<id>.authDir`, account-level overrides
+- operations: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`
+- session behavior: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
 
-## Voice notes (PTT audio)
+## Related
 
-WhatsApp sends audio as **voice notes** (PTT bubble).
-
-- Best results: OGG/Opus. OpenClaw rewrites `audio/ogg` to `audio/ogg; codecs=opus`.
-- `[[audio_as_voice]]` is ignored for WhatsApp (audio already ships as voice note).
-
-## Media limits + optimization
-
-- Default outbound cap: 5 MB (per media item).
-- Override: `agents.defaults.mediaMaxMb`.
-- Images are auto-optimized to JPEG under cap (resize + quality sweep).
-- Oversize media => error; media reply falls back to text warning.
-
-## Heartbeats
-
-- **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
-- **Agent heartbeat** can be configured per agent (`agents.list[].heartbeat`) or globally
-  via `agents.defaults.heartbeat` (fallback when no per-agent entries are set).
-  - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`) + `HEARTBEAT_OK` skip behavior.
-  - Delivery defaults to the last used channel (or configured target).
-
-## Reconnect behavior
-
-- Backoff policy: `web.reconnect`:
-  - `initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`.
-- If maxAttempts reached, web monitoring stops (degraded).
-- Logged-out => stop and require re-link.
-
-## Config quick map
-
-- `channels.whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
-- `channels.whatsapp.selfChatMode` (same-phone setup; bot uses your personal WhatsApp number).
-- `channels.whatsapp.allowFrom` (DM allowlist). WhatsApp uses E.164 phone numbers (no usernames).
-- `channels.whatsapp.mediaMaxMb` (inbound media save cap).
-- `channels.whatsapp.ackReaction` (auto-reaction on message receipt: `{emoji, direct, group}`).
-- `channels.whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).
-- `channels.whatsapp.accounts.<accountId>.mediaMaxMb` (per-account inbound media cap).
-- `channels.whatsapp.accounts.<accountId>.ackReaction` (per-account ack reaction override).
-- `channels.whatsapp.groupAllowFrom` (group sender allowlist).
-- `channels.whatsapp.groupPolicy` (group policy).
-- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit` (group history context; `0` disables).
-- `channels.whatsapp.dmHistoryLimit` (DM history limit in user turns). Per-user overrides: `channels.whatsapp.dms["<phone>"].historyLimit`.
-- `channels.whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
-- `channels.whatsapp.actions.reactions` (gate WhatsApp tool reactions).
-- `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`)
-- `messages.groupChat.historyLimit`
-- `channels.whatsapp.messagePrefix` (inbound prefix; per-account: `channels.whatsapp.accounts.<accountId>.messagePrefix`; deprecated: `messages.messagePrefix`)
-- `messages.responsePrefix` (outbound prefix)
-- `agents.defaults.mediaMaxMb`
-- `agents.defaults.heartbeat.every`
-- `agents.defaults.heartbeat.model` (optional override)
-- `agents.defaults.heartbeat.target`
-- `agents.defaults.heartbeat.to`
-- `agents.defaults.heartbeat.session`
-- `agents.list[].heartbeat.*` (per-agent overrides)
-- `session.*` (scope, idle, store, mainKey)
-- `web.enabled` (disable channel startup when false)
-- `web.heartbeatSeconds`
-- `web.reconnect.*`
-
-## Logs + troubleshooting
-
-- Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
-- Log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (configurable).
-- Troubleshooting guide: [Gateway troubleshooting](/gateway/troubleshooting).
-
-## Troubleshooting (quick)
-
-**Not linked / QR login required**
-
-- Symptom: `channels status` shows `linked: false` or warns “Not linked”.
-- Fix: run `openclaw channels login` on the gateway host and scan the QR (WhatsApp → Settings → Linked Devices).
-
-**Linked but disconnected / reconnect loop**
-
-- Symptom: `channels status` shows `running, disconnected` or warns “Linked but disconnected”.
-- Fix: `openclaw doctor` (or restart the gateway). If it persists, relink via `channels login` and inspect `openclaw logs --follow`.
-
-**Bun runtime**
-
-- Bun is **not recommended**. WhatsApp (Baileys) and Telegram are unreliable on Bun.
-  Run the gateway with **Node**. (See Getting Started runtime note.)
+- [Pairing](/channels/pairing)
+- [Channel routing](/channels/channel-routing)
+- [Troubleshooting](/channels/troubleshooting)

docs/ci.md

@@ -32,18 +32,6 @@ Jobs are ordered so cheap checks fail before expensive ones run:
 2. `build-artifacts` (blocked on above)
 3. `checks`, `checks-windows`, `macos`, `android` (blocked on build)
 
-## Code Analysis
-
-The `code-analysis` job runs `scripts/analyze_code_files.py` on PRs to enforce code quality:
-
-- **LOC threshold**: Files that grow past 1000 lines fail the build
-- **Delta-only**: Only checks files changed in the PR, not the entire codebase
-- **Push to main**: Skipped (job passes as no-op) so merges aren't blocked
-
-When `--strict` is set, violations block all downstream jobs. This catches bloated files early before expensive tests run.
-
-Excluded directories: `node_modules`, `dist`, `vendor`, `.git`, `coverage`, `Swabble`, `skills`, `.pi`
-
 ## Runners
 
 | Runner                          | Jobs                          |

docs/cli/hooks.md

@@ -32,13 +32,12 @@ List all discovered hooks from workspace, managed, and bundled directories.
 **Example output:**
 
 ```
-Hooks (4/4 ready)
+Hooks (3/3 ready)
 
 Ready:
   🚀 boot-md ✓ - Run BOOT.md on gateway startup
   📝 command-logger ✓ - Log all command events to a centralized audit file
   💾 session-memory ✓ - Save session context to memory when /new command is issued
-  😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
 ```
 
 **Example (verbose):**
@@ -277,18 +276,6 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 
 **See:** [command-logger documentation](/automation/hooks#command-logger)
 
-### soul-evil
-
-Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
-
-**Enable:**
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-**See:** [SOUL Evil Hook](/hooks/soul-evil)
-
 ### boot-md
 
 Runs `BOOT.md` when the gateway starts (after channels start).

docs/cli/index.md

@@ -303,7 +303,7 @@ Options:
 - `--non-interactive`
 - `--mode <local|remote>`
 - `--flow <quickstart|advanced|manual>` (manual is an alias for advanced)
-- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|skip>`
+- `--auth-choice <setup-token|token|chutes|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|moonshot-api-key-cn|kimi-code-api-key|synthetic-api-key|venice-api-key|gemini-api-key|zai-api-key|apiKey|minimax-api|minimax-api-lightning|opencode-zen|custom-api-key|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
 - `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
@@ -318,6 +318,11 @@ Options:
 - `--zai-api-key <key>`
 - `--minimax-api-key <key>`
 - `--opencode-zen-api-key <key>`
+- `--custom-base-url <url>` (non-interactive; used with `--auth-choice custom-api-key`)
+- `--custom-model-id <id>` (non-interactive; used with `--auth-choice custom-api-key`)
+- `--custom-api-key <key>` (non-interactive; optional; used with `--auth-choice custom-api-key`; falls back to `CUSTOM_API_KEY` when omitted)
+- `--custom-provider-id <id>` (non-interactive; optional custom provider id)
+- `--custom-compatibility <openai|anthropic>` (non-interactive; optional; default `openai`)
 - `--gateway-port <port>`
 - `--gateway-bind <loopback|lan|tailnet|auto|custom>`
 - `--gateway-auth <token|password>`

docs/cli/logs.md

@@ -21,4 +21,8 @@ openclaw logs
 openclaw logs --follow
 openclaw logs --json
 openclaw logs --limit 500
+openclaw logs --local-time
+openclaw logs --follow --local-time
 ```
+
+Use `--local-time` to render timestamps in your local timezone.

docs/cli/onboard.md

@@ -26,6 +26,36 @@ openclaw onboard --flow manual
 openclaw onboard --mode remote --remote-url ws://gateway-host:18789
 ```
 
+Non-interactive custom provider:
+
+```bash
+openclaw onboard --non-interactive \
+  --auth-choice custom-api-key \
+  --custom-base-url "https://llm.example.com/v1" \
+  --custom-model-id "foo-large" \
+  --custom-api-key "$CUSTOM_API_KEY" \
+  --custom-compatibility openai
+```
+
+`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
+
+Non-interactive Z.AI endpoint choices:
+
+Note: `--auth-choice zai-api-key` now auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5`).
+If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
+
+```bash
+# Promptless endpoint selection
+openclaw onboard --non-interactive \
+  --auth-choice zai-coding-global \
+  --zai-api-key "$ZAI_API_KEY"
+
+# Other Z.AI endpoint choices:
+# --auth-choice zai-coding-cn
+# --auth-choice zai-global
+# --auth-choice zai-cn
+```
+
 Flow notes:
 
 - `quickstart`: minimal prompts, auto-generates a gateway token.

docs/cli/plugins.md

@@ -1,5 +1,5 @@
 ---
-summary: "CLI reference for `openclaw plugins` (list, install, enable/disable, doctor)"
+summary: "CLI reference for `openclaw plugins` (list, install, uninstall, enable/disable, doctor)"
 read_when:
   - You want to install or manage in-process Gateway plugins
   - You want to debug plugin load failures
@@ -23,6 +23,7 @@ openclaw plugins list
 openclaw plugins info <id>
 openclaw plugins enable <id>
 openclaw plugins disable <id>
+openclaw plugins uninstall <id>
 openclaw plugins doctor
 openclaw plugins update <id>
 openclaw plugins update --all
@@ -51,6 +52,24 @@ Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
 openclaw plugins install -l ./my-plugin
 ```
 
+### Uninstall
+
+```bash
+openclaw plugins uninstall <id>
+openclaw plugins uninstall <id> --dry-run
+openclaw plugins uninstall <id> --keep-files
+```
+
+`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`,
+the plugin allowlist, and linked `plugins.load.paths` entries when applicable.
+For active memory plugins, the memory slot resets to `memory-core`.
+
+By default, uninstall also removes the plugin install directory under the active
+state dir extensions root (`$OPENCLAW_STATE_DIR/extensions/<id>`). Use
+`--keep-files` to keep files on disk.
+
+`--keep-config` is supported as a deprecated alias for `--keep-files`.
+
 ### Update
 
 ```bash

docs/cli/security.md

@@ -24,3 +24,4 @@ openclaw security audit --fix
 
 The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
 It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
+For webhook ingress, it warns when `hooks.defaultSessionKey` is unset, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.

docs/concepts/architecture.md

@@ -56,22 +56,6 @@ Protocol details:
 ## Connection lifecycle (single client)
 
 ```mermaid
-%%{init: {
-  'theme': 'base',
-  'themeVariables': {
-    'primaryColor': '#ffffff',
-    'primaryTextColor': '#000000',
-    'primaryBorderColor': '#000000',
-    'lineColor': '#000000',
-    'secondaryColor': '#f9f9fb',
-    'tertiaryColor': '#ffffff',
-    'clusterBkg': '#f9f9fb',
-    'clusterBorder': '#000000',
-    'nodeBorder': '#000000',
-    'mainBkg': '#ffffff',
-    'edgeLabelBackground': '#ffffff'
-  }
-}}%%
 sequenceDiagram
     participant Client
     participant Gateway

docs/concepts/memory.md

@@ -139,10 +139,11 @@ out to QMD for retrieval. Key points:
 - Boot refresh now runs in the background by default so chat startup is not
   blocked; set `memory.qmd.update.waitForBootSync = true` to keep the previous
   blocking behavior.
-- Searches run via `qmd query --json`, scoped to OpenClaw-managed collections.
-  If QMD fails or the binary is missing,
-  OpenClaw automatically falls back to the builtin SQLite manager so memory tools
-  keep working.
+- Searches run via `memory.qmd.searchMode` (default `qmd query --json`; also
+  supports `search` and `vsearch`). If the selected mode rejects flags on your
+  QMD build, OpenClaw retries with `qmd query`. If QMD fails or the binary is
+  missing, OpenClaw automatically falls back to the builtin SQLite manager so
+  memory tools keep working.
 - OpenClaw does not expose QMD embed batch-size tuning today; batch behavior is
   controlled by QMD itself.
 - **First search may be slow**: QMD may download local GGUF models (reranker/query
@@ -177,6 +178,8 @@ out to QMD for retrieval. Key points:
 **Config surface (`memory.qmd.*`)**
 
 - `command` (default `qmd`): override the executable path.
+- `searchMode` (default `query`): pick which QMD command backs
+  `memory_search` (`query`, `search`, `vsearch`).
 - `includeDefaultMemory` (default `true`): auto-index `MEMORY.md` + `memory/**/*.md`.
 - `paths[]`: add extra directories/files (`path`, optional `pattern`, optional
   stable `name`).

docs/concepts/session-tool.md

@@ -94,6 +94,7 @@ Behavior:
 - Announce delivery runs after the primary run completes and is best-effort; `status: "ok"` does not guarantee the announce was delivered.
 - Waits via gateway `agent.wait` (server-side) so reconnects don't drop the wait.
 - Agent-to-agent message context is injected for the primary run.
+- Inter-session messages are persisted with `message.provenance.kind = "inter_session"` so transcript readers can distinguish routed agent instructions from external user input.
 - After the primary run completes, OpenClaw runs a **reply-back loop**:
   - Round 2+ alternates between requester and target agents.
   - Reply exactly `REPLY_SKIP` to stop the ping‑pong.

docs/docs.json

@@ -24,6 +24,14 @@
     "dark": "#FF5A36",
     "light": "#FF8A6B"
   },
+  "styling": {
+    "codeblocks": {
+      "theme": {
+        "dark": "min-dark",
+        "light": "min-light"
+      }
+    }
+  },
   "navbar": {
     "links": [
       {
@@ -861,8 +869,8 @@
                 "pages": [
                   "channels/whatsapp",
                   "channels/telegram",
-                  "channels/grammy",
                   "channels/discord",
+                  "channels/irc",
                   "channels/slack",
                   "channels/feishu",
                   "channels/googlechat",
@@ -995,10 +1003,6 @@
                   "automation/auth-monitoring"
                 ]
               },
-              {
-                "group": "Hooks",
-                "pages": ["hooks/soul-evil"]
-              },
               {
                 "group": "Media and devices",
                 "pages": [
@@ -1035,6 +1039,7 @@
                   "providers/anthropic",
                   "providers/openai",
                   "providers/openrouter",
+                  "providers/litellm",
                   "providers/bedrock",
                   "providers/vercel-ai-gateway",
                   "providers/moonshot",
@@ -1098,6 +1103,7 @@
                     "group": "Configuration and operations",
                     "pages": [
                       "gateway/configuration",
+                      "gateway/configuration-reference",
                       "gateway/configuration-examples",
                       "gateway/authentication",
                       "gateway/health",
@@ -1218,7 +1224,7 @@
               },
               {
                 "group": "Technical reference",
-                "pages": ["reference/wizard", "reference/token-use"]
+                "pages": ["reference/wizard", "reference/token-use", "channels/grammy"]
               },
               {
                 "group": "Concept internals",
@@ -1376,7 +1382,6 @@
                 "pages": [
                   "zh-CN/channels/whatsapp",
                   "zh-CN/channels/telegram",
-                  "zh-CN/channels/grammy",
                   "zh-CN/channels/discord",
                   "zh-CN/channels/slack",
                   "zh-CN/channels/feishu",
@@ -1514,10 +1519,6 @@
                   "zh-CN/automation/auth-monitoring"
                 ]
               },
-              {
-                "group": "Hooks",
-                "pages": ["zh-CN/hooks/soul-evil"]
-              },
               {
                 "group": "媒体与设备",
                 "pages": [

docs/experiments/plans/browser-evaluate-cdp-refactor.md

@@ -0,0 +1,229 @@
+---
+summary: "Plan: isolate browser act:evaluate from Playwright queue using CDP, with end-to-end deadlines and safer ref resolution"
+owner: "openclaw"
+status: "draft"
+last_updated: "2026-02-10"
+title: "Browser Evaluate CDP Refactor"
+---
+
+# Browser Evaluate CDP Refactor Plan
+
+## Context
+
+`act:evaluate` executes user provided JavaScript in the page. Today it runs via Playwright
+(`page.evaluate` or `locator.evaluate`). Playwright serializes CDP commands per page, so a
+stuck or long running evaluate can block the page command queue and make every later action
+on that tab look "stuck".
+
+PR #13498 adds a pragmatic safety net (bounded evaluate, abort propagation, and best-effort
+recovery). This document describes a larger refactor that makes `act:evaluate` inherently
+isolated from Playwright so a stuck evaluate cannot wedge normal Playwright operations.
+
+## Goals
+
+- `act:evaluate` cannot permanently block later browser actions on the same tab.
+- Timeouts are single source of truth end to end so a caller can rely on a budget.
+- Abort and timeout are treated the same way across HTTP and in-process dispatch.
+- Element targeting for evaluate is supported without switching everything off Playwright.
+- Maintain backward compatibility for existing callers and payloads.
+
+## Non-goals
+
+- Replace all browser actions (click, type, wait, etc.) with CDP implementations.
+- Remove the existing safety net introduced in PR #13498 (it remains a useful fallback).
+- Introduce new unsafe capabilities beyond the existing `browser.evaluateEnabled` gate.
+- Add process isolation (worker process/thread) for evaluate. If we still see hard to recover
+  stuck states after this refactor, that is a follow-up idea.
+
+## Current Architecture (Why It Gets Stuck)
+
+At a high level:
+
+- Callers send `act:evaluate` to the browser control service.
+- The route handler calls into Playwright to execute the JavaScript.
+- Playwright serializes page commands, so an evaluate that never finishes blocks the queue.
+- A stuck queue means later click/type/wait operations on the tab can appear to hang.
+
+## Proposed Architecture
+
+### 1. Deadline Propagation
+
+Introduce a single budget concept and derive everything from it:
+
+- Caller sets `timeoutMs` (or a deadline in the future).
+- The outer request timeout, route handler logic, and the execution budget inside the page
+  all use the same budget, with small headroom where needed for serialization overhead.
+- Abort is propagated as an `AbortSignal` everywhere so cancellation is consistent.
+
+Implementation direction:
+
+- Add a small helper (for example `createBudget({ timeoutMs, signal })`) that returns:
+  - `signal`: the linked AbortSignal
+  - `deadlineAtMs`: absolute deadline
+  - `remainingMs()`: remaining budget for child operations
+- Use this helper in:
+  - `src/browser/client-fetch.ts` (HTTP and in-process dispatch)
+  - `src/node-host/runner.ts` (proxy path)
+  - browser action implementations (Playwright and CDP)
+
+### 2. Separate Evaluate Engine (CDP Path)
+
+Add a CDP based evaluate implementation that does not share Playwright's per page command
+queue. The key property is that the evaluate transport is a separate WebSocket connection
+and a separate CDP session attached to the target.
+
+Implementation direction:
+
+- New module, for example `src/browser/cdp-evaluate.ts`, that:
+  - Connects to the configured CDP endpoint (browser level socket).
+  - Uses `Target.attachToTarget({ targetId, flatten: true })` to get a `sessionId`.
+  - Runs either:
+    - `Runtime.evaluate` for page level evaluate, or
+    - `DOM.resolveNode` plus `Runtime.callFunctionOn` for element evaluate.
+  - On timeout or abort:
+    - Sends `Runtime.terminateExecution` best-effort for the session.
+    - Closes the WebSocket and returns a clear error.
+
+Notes:
+
+- This still executes JavaScript in the page, so termination can have side effects. The win
+  is that it does not wedge the Playwright queue, and it is cancelable at the transport
+  layer by killing the CDP session.
+
+### 3. Ref Story (Element Targeting Without A Full Rewrite)
+
+The hard part is element targeting. CDP needs a DOM handle or `backendDOMNodeId`, while
+today most browser actions use Playwright locators based on refs from snapshots.
+
+Recommended approach: keep existing refs, but attach an optional CDP resolvable id.
+
+#### 3.1 Extend Stored Ref Info
+
+Extend the stored role ref metadata to optionally include a CDP id:
+
+- Today: `{ role, name, nth }`
+- Proposed: `{ role, name, nth, backendDOMNodeId?: number }`
+
+This keeps all existing Playwright based actions working and allows CDP evaluate to accept
+the same `ref` value when the `backendDOMNodeId` is available.
+
+#### 3.2 Populate backendDOMNodeId At Snapshot Time
+
+When producing a role snapshot:
+
+1. Generate the existing role ref map as today (role, name, nth).
+2. Fetch the AX tree via CDP (`Accessibility.getFullAXTree`) and compute a parallel map of
+   `(role, name, nth) -> backendDOMNodeId` using the same duplicate handling rules.
+3. Merge the id back into the stored ref info for the current tab.
+
+If mapping fails for a ref, leave `backendDOMNodeId` undefined. This makes the feature
+best-effort and safe to roll out.
+
+#### 3.3 Evaluate Behavior With Ref
+
+In `act:evaluate`:
+
+- If `ref` is present and has `backendDOMNodeId`, run element evaluate via CDP.
+- If `ref` is present but has no `backendDOMNodeId`, fall back to the Playwright path (with
+  the safety net).
+
+Optional escape hatch:
+
+- Extend the request shape to accept `backendDOMNodeId` directly for advanced callers (and
+  for debugging), while keeping `ref` as the primary interface.
+
+### 4. Keep A Last Resort Recovery Path
+
+Even with CDP evaluate, there are other ways to wedge a tab or a connection. Keep the
+existing recovery mechanisms (terminate execution + disconnect Playwright) as a last resort
+for:
+
+- legacy callers
+- environments where CDP attach is blocked
+- unexpected Playwright edge cases
+
+## Implementation Plan (Single Iteration)
+
+### Deliverables
+
+- A CDP based evaluate engine that runs outside the Playwright per-page command queue.
+- A single end-to-end timeout/abort budget used consistently by callers and handlers.
+- Ref metadata that can optionally carry `backendDOMNodeId` for element evaluate.
+- `act:evaluate` prefers the CDP engine when possible and falls back to Playwright when not.
+- Tests that prove a stuck evaluate does not wedge later actions.
+- Logs/metrics that make failures and fallbacks visible.
+
+### Implementation Checklist
+
+1. Add a shared "budget" helper to link `timeoutMs` + upstream `AbortSignal` into:
+   - a single `AbortSignal`
+   - an absolute deadline
+   - a `remainingMs()` helper for downstream operations
+2. Update all caller paths to use that helper so `timeoutMs` means the same thing everywhere:
+   - `src/browser/client-fetch.ts` (HTTP and in-process dispatch)
+   - `src/node-host/runner.ts` (node proxy path)
+   - CLI wrappers that call `/act` (add `--timeout-ms` to `browser evaluate`)
+3. Implement `src/browser/cdp-evaluate.ts`:
+   - connect to the browser-level CDP socket
+   - `Target.attachToTarget` to get a `sessionId`
+   - run `Runtime.evaluate` for page evaluate
+   - run `DOM.resolveNode` + `Runtime.callFunctionOn` for element evaluate
+   - on timeout/abort: best-effort `Runtime.terminateExecution` then close the socket
+4. Extend stored role ref metadata to optionally include `backendDOMNodeId`:
+   - keep existing `{ role, name, nth }` behavior for Playwright actions
+   - add `backendDOMNodeId?: number` for CDP element targeting
+5. Populate `backendDOMNodeId` during snapshot creation (best-effort):
+   - fetch AX tree via CDP (`Accessibility.getFullAXTree`)
+   - compute `(role, name, nth) -> backendDOMNodeId` and merge into the stored ref map
+   - if mapping is ambiguous or missing, leave the id undefined
+6. Update `act:evaluate` routing:
+   - if no `ref`: always use CDP evaluate
+   - if `ref` resolves to a `backendDOMNodeId`: use CDP element evaluate
+   - otherwise: fall back to Playwright evaluate (still bounded and abortable)
+7. Keep the existing "last resort" recovery path as a fallback, not the default path.
+8. Add tests:
+   - stuck evaluate times out within budget and the next click/type succeeds
+   - abort cancels evaluate (client disconnect or timeout) and unblocks subsequent actions
+   - mapping failures cleanly fall back to Playwright
+9. Add observability:
+   - evaluate duration and timeout counters
+   - terminateExecution usage
+   - fallback rate (CDP -> Playwright) and reasons
+
+### Acceptance Criteria
+
+- A deliberately hung `act:evaluate` returns within the caller budget and does not wedge the
+  tab for later actions.
+- `timeoutMs` behaves consistently across CLI, agent tool, node proxy, and in-process calls.
+- If `ref` can be mapped to `backendDOMNodeId`, element evaluate uses CDP; otherwise the
+  fallback path is still bounded and recoverable.
+
+## Testing Plan
+
+- Unit tests:
+  - `(role, name, nth)` matching logic between role refs and AX tree nodes.
+  - Budget helper behavior (headroom, remaining time math).
+- Integration tests:
+  - CDP evaluate timeout returns within budget and does not block the next action.
+  - Abort cancels evaluate and triggers termination best-effort.
+- Contract tests:
+  - Ensure `BrowserActRequest` and `BrowserActResponse` remain compatible.
+
+## Risks And Mitigations
+
+- Mapping is imperfect:
+  - Mitigation: best-effort mapping, fallback to Playwright evaluate, and add debug tooling.
+- `Runtime.terminateExecution` has side effects:
+  - Mitigation: only use on timeout/abort and document the behavior in errors.
+- Extra overhead:
+  - Mitigation: only fetch AX tree when snapshots are requested, cache per target, and keep
+    CDP session short lived.
+- Extension relay limitations:
+  - Mitigation: use browser level attach APIs when per page sockets are not available, and
+    keep the current Playwright path as fallback.
+
+## Open Questions
+
+- Should the new engine be configurable as `playwright`, `cdp`, or `auto`?
+- Do we want to expose a new "nodeRef" format for advanced users, or keep `ref` only?
+- How should frame snapshots and selector scoped snapshots participate in AX mapping?

docs/gateway/configuration-examples.md

@@ -67,7 +67,11 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
   // Auth profile metadata (secrets live in auth-profiles.json)
   auth: {
     profiles: {
-      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
+      "anthropic:me@example.com": {
+        provider: "anthropic",
+        mode: "oauth",
+        email: "me@example.com",
+      },
       "anthropic:work": { provider: "anthropic", mode: "api_key" },
       "openai:default": { provider: "openai", mode: "api_key" },
       "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
@@ -375,7 +379,10 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
         to: "+15555550123",
         thinking: "low",
         timeoutSeconds: 300,
-        transform: { module: "./transforms/gmail.js", export: "transformGmail" },
+        transform: {
+          module: "./transforms/gmail.js",
+          export: "transformGmail",
+        },
       },
     ],
     gmail: {

docs/gateway/index.md

@@ -5,120 +5,173 @@ read_when:
 title: "Gateway Runbook"
 ---
 
-# Gateway service runbook
+# Gateway runbook
 
-Last updated: 2025-12-09
+Use this page for day-1 startup and day-2 operations of the Gateway service.
 
-## What it is
+<CardGroup cols={2}>
+  <Card title="Deep troubleshooting" icon="siren" href="/gateway/troubleshooting">
+    Symptom-first diagnostics with exact command ladders and log signatures.
+  </Card>
+  <Card title="Configuration" icon="sliders" href="/gateway/configuration">
+    Task-oriented setup guide + full configuration reference.
+  </Card>
+</CardGroup>
 
-- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
-- Replaces the legacy `gateway` command. CLI entry point: `openclaw gateway`.
-- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
+## 5-minute local startup
 
-## How to run (local)
+<Steps>
+  <Step title="Start the Gateway">
 
 ```bash
 openclaw gateway --port 18789
-# for full debug/trace logs in stdio:
+# debug/trace mirrored to stdio
 openclaw gateway --port 18789 --verbose
-# if the port is busy, terminate listeners then start:
+# force-kill listener on selected port, then start
 openclaw gateway --force
-# dev loop (auto-reload on TS changes):
-pnpm gateway:watch
 ```
 
-- Config hot reload watches `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`).
-  - Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
-  - Hot reload uses in-process restart via **SIGUSR1** when needed.
-  - Disable with `gateway.reload.mode="off"`.
-- Binds WebSocket control plane to `127.0.0.1:<port>` (default 18789).
-- The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex.
-  - OpenAI Chat Completions (HTTP): [`/v1/chat/completions`](/gateway/openai-http-api).
-  - OpenResponses (HTTP): [`/v1/responses`](/gateway/openresponses-http-api).
-  - Tools Invoke (HTTP): [`/tools/invoke`](/gateway/tools-invoke-http-api).
-- Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://<gateway-host>:18793/__openclaw__/canvas/` from `~/.openclaw/workspace/canvas`. Disable with `canvasHost.enabled=false` or `OPENCLAW_SKIP_CANVAS_HOST=1`.
-- Logs to stdout; use launchd/systemd to keep it alive and rotate logs.
-- Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting.
-- `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing).
-- If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash.
-- **SIGUSR1** triggers an in-process restart when authorized (gateway tool/config apply/update, or enable `commands.restart` for manual restarts).
-- Gateway auth is required by default: set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) or `gateway.auth.password`. Clients must send `connect.params.auth.token/password` unless using Tailscale Serve identity.
-- The wizard now generates a token by default, even on loopback.
-- Port precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > default `18789`.
+  </Step>
+
+  <Step title="Verify service health">
+
+```bash
+openclaw gateway status
+openclaw status
+openclaw logs --follow
+```
+
+Healthy baseline: `Runtime: running` and `RPC probe: ok`.
+
+  </Step>
+
+  <Step title="Validate channel readiness">
+
+```bash
+openclaw channels status --probe
+```
+
+  </Step>
+</Steps>
+
+<Note>
+Gateway config reload watches the active config file path (resolved from profile/state defaults, or `OPENCLAW_CONFIG_PATH` when set).
+Default mode is `gateway.reload.mode="hybrid"`.
+</Note>
+
+## Runtime model
+
+- One always-on process for routing, control plane, and channel connections.
+- Single multiplexed port for:
+  - WebSocket control/RPC
+  - HTTP APIs (OpenAI-compatible, Responses, tools invoke)
+  - Control UI and hooks
+- Default bind mode: `loopback`.
+- Auth is required by default (`gateway.auth.token` / `gateway.auth.password`, or `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`).
+
+### Port and bind precedence
+
+| Setting      | Resolution order                                              |
+| ------------ | ------------------------------------------------------------- |
+| Gateway port | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
+| Bind mode    | CLI/override → `gateway.bind` → `loopback`                    |
+
+### Hot reload modes
+
+| `gateway.reload.mode` | Behavior                                   |
+| --------------------- | ------------------------------------------ |
+| `off`                 | No config reload                           |
+| `hot`                 | Apply only hot-safe changes                |
+| `restart`             | Restart on reload-required changes         |
+| `hybrid` (default)    | Hot-apply when safe, restart when required |
+
+## Operator command set
+
+```bash
+openclaw gateway status
+openclaw gateway status --deep
+openclaw gateway status --json
+openclaw gateway install
+openclaw gateway restart
+openclaw gateway stop
+openclaw logs --follow
+openclaw doctor
+```
 
 ## 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.
-
-## Multiple gateways (same host)
-
-Usually unnecessary: one Gateway can serve multiple messaging channels and agents. Use multiple Gateways only for redundancy or strict isolation (ex: rescue bot).
-
-Supported if you isolate state + config and use unique ports. Full guide: [Multiple gateways](/gateway/multiple-gateways).
-
-Service names are profile-aware:
-
-- macOS: `bot.molt.<profile>` (legacy `com.openclaw.*` may still exist)
-- Linux: `openclaw-gateway-<profile>.service`
-- Windows: `OpenClaw Gateway (<profile>)`
-
-Install metadata is embedded in the service config:
-
-- `OPENCLAW_SERVICE_MARKER=openclaw`
-- `OPENCLAW_SERVICE_KIND=gateway`
-- `OPENCLAW_SERVICE_VERSION=<version>`
-
-Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state dir, workspace, and base port spacing. Full guide: [Rescue-bot guide](/gateway/multiple-gateways#rescue-bot-guide).
-
-### Dev profile (`--dev`)
-
-Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup.
+Preferred: Tailscale/VPN.
+Fallback: SSH tunnel.
 
 ```bash
-openclaw --dev setup
-openclaw --dev gateway --allow-unconfigured
-# then target the dev instance:
-openclaw --dev status
-openclaw --dev health
+ssh -N -L 18789:127.0.0.1:18789 user@host
 ```
 
-Defaults (can be overridden via env/flags/config):
+Then connect clients to `ws://127.0.0.1:18789` locally.
 
-- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
-- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
-- `OPENCLAW_GATEWAY_PORT=19001` (Gateway WS + HTTP)
-- browser control service port = `19003` (derived: `gateway.port+2`, loopback only)
-- `canvasHost.port=19005` (derived: `gateway.port+4`)
-- `agents.defaults.workspace` default becomes `~/.openclaw/workspace-dev` when you run `setup`/`onboard` under `--dev`.
+<Warning>
+If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.
+</Warning>
 
-Derived ports (rules of thumb):
+See: [Remote Gateway](/gateway/remote), [Authentication](/gateway/authentication), [Tailscale](/gateway/tailscale).
 
-- Base port = `gateway.port` (or `OPENCLAW_GATEWAY_PORT` / `--port`)
-- browser control service port = base + 2 (loopback only)
-- `canvasHost.port = base + 4` (or `OPENCLAW_CANVAS_HOST_PORT` / config override)
-- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
+## Supervision and service lifecycle
+
+Use supervised runs for production-like reliability.
+
+<Tabs>
+  <Tab title="macOS (launchd)">
+
+```bash
+openclaw gateway install
+openclaw gateway status
+openclaw gateway restart
+openclaw gateway stop
+```
+
+LaunchAgent labels are `ai.openclaw.gateway` (default) or `ai.openclaw.<profile>` (named profile). `openclaw doctor` audits and repairs service config drift.
+
+  </Tab>
+
+  <Tab title="Linux (systemd user)">
+
+```bash
+openclaw gateway install
+systemctl --user enable --now openclaw-gateway[-<profile>].service
+openclaw gateway status
+```
+
+For persistence after logout, enable lingering:
+
+```bash
+sudo loginctl enable-linger <user>
+```
+
+  </Tab>
+
+  <Tab title="Linux (system service)">
+
+Use a system unit for multi-user/always-on hosts.
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now openclaw-gateway[-<profile>].service
+```
+
+  </Tab>
+</Tabs>
+
+## Multiple gateways on one host
+
+Most setups should run **one** Gateway.
+Use multiple only for strict isolation/redundancy (for example a rescue profile).
 
 Checklist per instance:
 
-- unique `gateway.port`
-- unique `OPENCLAW_CONFIG_PATH`
-- unique `OPENCLAW_STATE_DIR`
-- unique `agents.defaults.workspace`
-- separate WhatsApp numbers (if using WA)
-
-Service install per profile:
-
-```bash
-openclaw --profile main gateway install
-openclaw --profile rescue gateway install
-```
+- Unique `gateway.port`
+- Unique `OPENCLAW_CONFIG_PATH`
+- Unique `OPENCLAW_STATE_DIR`
+- Unique `agents.defaults.workspace`
 
 Example:
 
@@ -127,204 +180,75 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla
 OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
 ```
 
-## Protocol (operator view)
+See: [Multiple gateways](/gateway/multiple-gateways).
 
-- Full docs: [Gateway protocol](/gateway/protocol) and [Bridge protocol (legacy)](/gateway/bridge-protocol).
-- Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`.
-- Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes).
-- After handshake:
-  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
-  - Events: `{type:"event", event, payload, seq?, stateVersion?}`
-- Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }` (for WS clients, `instanceId` comes from `connect.client.instanceId`).
-- `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`.
-
-## Methods (initial set)
-
-- `health` — full health snapshot (same shape as `openclaw health --json`).
-- `status` — short summary.
-- `system-presence` — current presence list.
-- `system-event` — post a presence/system note (structured).
-- `send` — send a message via the active channel(s).
-- `agent` — run an agent turn (streams events back on same connection).
-- `node.list` — list paired + currently-connected nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`).
-- `node.describe` — describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes).
-- `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
-- `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
-
-See also: [Presence](/concepts/presence) for how presence is produced/deduped and why a stable `client.instanceId` matters.
-
-## Events
-
-- `agent` — streamed tool/output events from the agent run (seq-tagged).
-- `presence` — presence updates (deltas with stateVersion) pushed to all connected clients.
-- `tick` — periodic keepalive/no-op to confirm liveness.
-- `shutdown` — Gateway is exiting; payload includes `reason` and optional `restartExpectedMs`. Clients should reconnect.
-
-## WebChat integration
-
-- WebChat is a native SwiftUI UI that talks directly to the Gateway WebSocket for history, sends, abort, and events.
-- Remote use goes through the same SSH/Tailscale tunnel; if a gateway token is configured, the client includes it during `connect`.
-- macOS app connects via a single WS (shared connection); it hydrates presence from the initial snapshot and listens for `presence` events to update the UI.
-
-## Typing and validation
-
-- Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions.
-- Clients (TS/Swift) consume generated types (TS directly; Swift via the repo’s generator).
-- Protocol definitions are the source of truth; regenerate schema/models with:
-  - `pnpm protocol:gen`
-  - `pnpm protocol:gen:swift`
-
-## Connection snapshot
-
-- `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests.
-- `health`/`system-presence` remain available for manual refresh, but are not required at connect time.
-
-## Error codes (res.error shape)
-
-- Errors use `{ code, message, details?, retryable?, retryAfterMs? }`.
-- Standard codes:
-  - `NOT_LINKED` — WhatsApp not authenticated.
-  - `AGENT_TIMEOUT` — agent did not respond within the configured deadline.
-  - `INVALID_REQUEST` — schema/param validation failed.
-  - `UNAVAILABLE` — Gateway is shutting down or a dependency is unavailable.
-
-## Keepalive behavior
-
-- `tick` events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs.
-- Send/agent acknowledgements remain separate responses; do not overload ticks for sends.
-
-## Replay / gaps
-
-- Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap.
-
-## Supervision (macOS example)
-
-- Use launchd to keep the service alive:
-  - Program: path to `openclaw`
-  - Arguments: `gateway`
-  - KeepAlive: true
-  - StandardOut/Err: file paths or `syslog`
-- On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices.
-- LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped).
-  - `openclaw gateway install` writes `~/Library/LaunchAgents/bot.molt.gateway.plist`
-    (or `bot.molt.<profile>.plist`; legacy `com.openclaw.*` is cleaned up).
-  - `openclaw doctor` audits the LaunchAgent config and can update it to current defaults.
-
-## Gateway service management (CLI)
-
-Use the Gateway CLI for install/start/stop/restart/status:
+### Dev profile quick path
 
 ```bash
-openclaw gateway status
-openclaw gateway install
-openclaw gateway stop
-openclaw gateway restart
-openclaw logs --follow
+openclaw --dev setup
+openclaw --dev gateway --allow-unconfigured
+openclaw --dev status
 ```
 
-Notes:
+Defaults include isolated state/config and base gateway port `19001`.
 
-- `gateway status` probes the Gateway RPC by default using the service’s resolved port/config (override with `--url`).
-- `gateway status --deep` adds system-level scans (LaunchDaemons/system units).
-- `gateway status --no-probe` skips the RPC probe (useful when networking is down).
-- `gateway status --json` is stable for scripts.
-- `gateway status` reports **supervisor runtime** (launchd/systemd running) separately from **RPC reachability** (WS connect + status RPC).
-- `gateway status` prints config path + probe target to avoid “localhost vs LAN bind” confusion and profile mismatches.
-- `gateway status` includes the last gateway error line when the service looks running but the port is closed.
-- `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed).
-- If other gateway-like services are detected, the CLI warns unless they are OpenClaw profile services.
-  We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](/gateway/multiple-gateways).
-  - Cleanup: `openclaw gateway uninstall` (current service) and `openclaw doctor` (legacy migrations).
-- `gateway install` is a no-op when already installed; use `openclaw gateway install --force` to reinstall (profile/env/path changes).
+## Protocol quick reference (operator view)
 
-Bundled mac app:
+- First client frame must be `connect`.
+- Gateway returns `hello-ok` snapshot (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
+- Requests: `req(method, params)` → `res(ok/payload|error)`.
+- Common events: `connect.challenge`, `agent`, `chat`, `presence`, `tick`, `health`, `heartbeat`, `shutdown`.
 
-- OpenClaw.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled
-  `bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.openclaw.*` labels still unload cleanly).
-- To stop it cleanly, use `openclaw gateway stop` (or `launchctl bootout gui/$UID/bot.molt.gateway`).
-- To restart, use `openclaw gateway restart` (or `launchctl kickstart -k gui/$UID/bot.molt.gateway`).
-  - `launchctl` only works if the LaunchAgent is installed; otherwise use `openclaw gateway install` first.
-  - Replace the label with `bot.molt.<profile>` when running a named profile.
+Agent runs are two-stage:
 
-## Supervision (systemd user unit)
+1. Immediate accepted ack (`status:"accepted"`)
+2. Final completion response (`status:"ok"|"error"`), with streamed `agent` events in between.
 
-OpenClaw installs a **systemd user service** by default on Linux/WSL2. We
-recommend user services for single-user machines (simpler env, per-user config).
-Use a **system service** for multi-user or always-on servers (no lingering
-required, shared supervision).
-
-`openclaw gateway install` writes the user unit. `openclaw doctor` audits the
-unit and can update it to match the current recommended defaults.
-
-Create `~/.config/systemd/user/openclaw-gateway[-<profile>].service`:
-
-```
-[Unit]
-Description=OpenClaw Gateway (profile: <profile>, v<version>)
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-ExecStart=/usr/local/bin/openclaw gateway --port 18789
-Restart=always
-RestartSec=5
-Environment=OPENCLAW_GATEWAY_TOKEN=
-WorkingDirectory=/home/youruser
-
-[Install]
-WantedBy=default.target
-```
-
-Enable lingering (required so the user service survives logout/idle):
-
-```
-sudo loginctl enable-linger youruser
-```
-
-Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`).
-Then enable the service:
-
-```
-systemctl --user enable --now openclaw-gateway[-<profile>].service
-```
-
-**Alternative (system service)** - for always-on or multi-user servers, you can
-install a systemd **system** unit instead of a user unit (no lingering needed).
-Create `/etc/systemd/system/openclaw-gateway[-<profile>].service` (copy the unit above,
-switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then:
-
-```
-sudo systemctl daemon-reload
-sudo systemctl enable --now openclaw-gateway[-<profile>].service
-```
-
-## Windows (WSL2)
-
-Windows installs should use **WSL2** and follow the Linux systemd section above.
+See full protocol docs: [Gateway Protocol](/gateway/protocol).
 
 ## Operational checks
 
-- Liveness: open WS and send `req:connect` → expect `res` with `payload.type="hello-ok"` (with snapshot).
-- Readiness: call `health` → expect `ok: true` and a linked channel in `linkChannel` (when applicable).
-- Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients.
+### Liveness
+
+- Open WS and send `connect`.
+- Expect `hello-ok` response with snapshot.
+
+### Readiness
+
+```bash
+openclaw gateway status
+openclaw channels status --probe
+openclaw health
+```
+
+### Gap recovery
+
+Events are not replayed. On sequence gaps, refresh state (`health`, `system-presence`) before continuing.
+
+## Common failure signatures
+
+| Signature                                                      | Likely issue                             |
+| -------------------------------------------------------------- | ---------------------------------------- |
+| `refusing to bind gateway ... without auth`                    | Non-loopback bind without token/password |
+| `another gateway instance is already listening` / `EADDRINUSE` | Port conflict                            |
+| `Gateway start blocked: set gateway.mode=local`                | Config set to remote mode                |
+| `unauthorized` during connect                                  | Auth mismatch between client and gateway |
+
+For full diagnosis ladders, use [Gateway Troubleshooting](/gateway/troubleshooting).
 
 ## Safety guarantees
 
-- Assume one Gateway per host by default; if you run multiple profiles, isolate ports/state and target the right instance.
-- No fallback to direct Baileys connections; if the Gateway is down, sends fail fast.
-- Non-connect first frames or malformed JSON are rejected and the socket is closed.
-- Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect.
+- Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
+- Invalid/non-connect first frames are rejected and closed.
+- Graceful shutdown emits `shutdown` event before socket close.
 
-## CLI helpers
+---
 
-- `openclaw gateway health|status` — request health/status over the Gateway WS.
-- `openclaw message send --target <num> --message "hi" [--media ...]` — send via Gateway (idempotent for WhatsApp).
-- `openclaw agent --message "hi" --to <num>` — run an agent turn (waits for final by default).
-- `openclaw gateway call <method> --params '{"k":"v"}'` — raw method invoker for debugging.
-- `openclaw gateway stop|restart` — stop/restart the supervised gateway service (launchd/systemd).
-- Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one.
+Related:
 
-## Migration guidance
-
-- Retire uses of `openclaw gateway` and the legacy TCP control port.
-- Update clients to speak the WS protocol with mandatory connect and structured presence.
+- [Troubleshooting](/gateway/troubleshooting)
+- [Background Process](/gateway/background-process)
+- [Configuration](/gateway/configuration)
+- [Health](/gateway/health)
+- [Doctor](/gateway/doctor)
+- [Authentication](/gateway/authentication)

docs/gateway/openresponses-http-api.md

@@ -186,7 +186,11 @@ URL fetch defaults:
 
 - `files.allowUrl`: `true`
 - `images.allowUrl`: `true`
+- `maxUrlParts`: `8` (total URL-based `input_file` + `input_image` parts per request)
 - Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).
+- Optional hostname allowlists are supported per input type (`files.urlAllowlist`, `images.urlAllowlist`).
+  - Exact host: `"cdn.example.com"`
+  - Wildcard subdomains: `"*.assets.example.com"` (does not match apex)
 
 ## File + image limits (config)
 
@@ -200,8 +204,10 @@ Defaults can be tuned under `gateway.http.endpoints.responses`:
         responses: {
           enabled: true,
           maxBodyBytes: 20000000,
+          maxUrlParts: 8,
           files: {
             allowUrl: true,
+            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
             allowedMimes: [
               "text/plain",
               "text/markdown",
@@ -222,6 +228,7 @@ Defaults can be tuned under `gateway.http.endpoints.responses`:
           },
           images: {
             allowUrl: true,
+            urlAllowlist: ["images.example.com"],
             allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
             maxBytes: 10485760,
             maxRedirects: 3,
@@ -237,6 +244,7 @@ Defaults can be tuned under `gateway.http.endpoints.responses`:
 Defaults when omitted:
 
 - `maxBodyBytes`: 20MB
+- `maxUrlParts`: 8
 - `files.maxBytes`: 5MB
 - `files.maxChars`: 200k
 - `files.maxRedirects`: 3
@@ -248,6 +256,13 @@ Defaults when omitted:
 - `images.maxRedirects`: 3
 - `images.timeoutMs`: 10s
 
+Security note:
+
+- URL allowlists are enforced before fetch and on redirect hops.
+- Allowlisting a hostname does not bypass private/internal IP blocking.
+- For internet-exposed gateways, apply network egress controls in addition to app-level guards.
+  See [Security](/gateway/security).
+
 ## Streaming (SSE)
 
 Set `stream: true` to receive Server-Sent Events (SSE):

docs/gateway/remote-gateway-readme.md

@@ -11,22 +11,6 @@ OpenClaw.app uses SSH tunneling to connect to a remote gateway. This guide shows
 ## Overview
 
 ```mermaid
-%%{init: {
-  'theme': 'base',
-  'themeVariables': {
-    'primaryColor': '#ffffff',
-    'primaryTextColor': '#000000',
-    'primaryBorderColor': '#000000',
-    'lineColor': '#000000',
-    'secondaryColor': '#f9f9fb',
-    'tertiaryColor': '#ffffff',
-    'clusterBkg': '#f9f9fb',
-    'clusterBorder': '#000000',
-    'nodeBorder': '#000000',
-    'mainBkg': '#ffffff',
-    'edgeLabelBackground': '#ffffff'
-  }
-}}%%
 flowchart TB
     subgraph Client["Client Machine"]
         direction TB

docs/gateway/security/index.md

@@ -265,6 +265,9 @@ tool calls. Reduce the blast radius by:
 - Using a read-only or tool-disabled **reader agent** to summarize untrusted content,
   then pass the summary to your main agent.
 - Keeping `web_search` / `web_fetch` / `browser` off for tool-enabled agents unless needed.
+- For OpenResponses URL inputs (`input_file` / `input_image`), set tight
+  `gateway.http.endpoints.responses.files.urlAllowlist` and
+  `gateway.http.endpoints.responses.images.urlAllowlist`, and keep `maxUrlParts` low.
 - Enabling sandboxing and strict tool allowlists for any agent that touches untrusted input.
 - Keeping secrets out of prompts; pass them via env/config on the gateway host instead.
 
@@ -798,22 +801,6 @@ Commit the updated `.secrets.baseline` once it reflects the intended state.
 ## The Trust Hierarchy
 
 ```mermaid
-%%{init: {
-  'theme': 'base',
-  'themeVariables': {
-    'primaryColor': '#ffffff',
-    'primaryTextColor': '#000000',
-    'primaryBorderColor': '#000000',
-    'lineColor': '#000000',
-    'secondaryColor': '#f9f9fb',
-    'tertiaryColor': '#ffffff',
-    'clusterBkg': '#f9f9fb',
-    'clusterBorder': '#000000',
-    'nodeBorder': '#000000',
-    'mainBkg': '#ffffff',
-    'edgeLabelBackground': '#ffffff'
-  }
-}}%%
 flowchart TB
     A["Owner (Peter)"] -- Full trust --> B["AI (Clawd)"]
     B -- Trust but verify --> C["Friends in allowlist"]

docs/help/faq.md

@@ -546,6 +546,15 @@ For a hackable (git) install:
 curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
 ```
 
+Windows (PowerShell) equivalent:
+
+```powershell
+# install.ps1 has no dedicated -Verbose flag yet.
+Set-PSDebug -Trace 1
+& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+Set-PSDebug -Trace 0
+```
+
 More options: [Installer flags](/install/installer).
 
 ### Windows install says git not found or openclaw not recognized

docs/hooks/soul-evil.md

@@ -1,69 +0,0 @@
----
-summary: "SOUL Evil hook (swap SOUL.md with SOUL_EVIL.md)"
-read_when:
-  - You want to enable or tune the SOUL Evil hook
-  - You want a purge window or random-chance persona swap
-title: "SOUL Evil Hook"
----
-
-# SOUL Evil Hook
-
-The SOUL Evil hook swaps the **injected** `SOUL.md` content with `SOUL_EVIL.md` during
-a purge window or by random chance. It does **not** modify files on disk.
-
-## How It Works
-
-When `agent:bootstrap` runs, the hook can replace the `SOUL.md` content in memory
-before the system prompt is assembled. If `SOUL_EVIL.md` is missing or empty,
-OpenClaw logs a warning and keeps the normal `SOUL.md`.
-
-Sub-agent runs do **not** include `SOUL.md` in their bootstrap files, so this hook
-has no effect on sub-agents.
-
-## Enable
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-Then set the config:
-
-```json
-{
-  "hooks": {
-    "internal": {
-      "enabled": true,
-      "entries": {
-        "soul-evil": {
-          "enabled": true,
-          "file": "SOUL_EVIL.md",
-          "chance": 0.1,
-          "purge": { "at": "21:00", "duration": "15m" }
-        }
-      }
-    }
-  }
-}
-```
-
-Create `SOUL_EVIL.md` in the agent workspace root (next to `SOUL.md`).
-
-## Options
-
-- `file` (string): alternate SOUL filename (default: `SOUL_EVIL.md`)
-- `chance` (number 0–1): random chance per run to use `SOUL_EVIL.md`
-- `purge.at` (HH:mm): daily purge start (24-hour clock)
-- `purge.duration` (duration): window length (e.g. `30s`, `10m`, `1h`)
-
-**Precedence:** purge window wins over chance.
-
-**Timezone:** uses `agents.defaults.userTimezone` when set; otherwise host timezone.
-
-## Notes
-
-- No files are written or modified on disk.
-- If `SOUL.md` is not in the bootstrap list, the hook does nothing.
-
-## See Also
-
-- [Hooks](/automation/hooks)

docs/install/hetzner.md

@@ -329,3 +329,24 @@ All long-lived state must survive restarts, rebuilds, and reboots.
 | Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
 | OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
 | Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |
+
+---
+
+## Infrastructure as Code (Terraform)
+
+For teams preferring infrastructure-as-code workflows, a community-maintained Terraform setup provides:
+
+- Modular Terraform configuration with remote state management
+- Automated provisioning via cloud-init
+- Deployment scripts (bootstrap, deploy, backup/restore)
+- Security hardening (firewall, UFW, SSH-only access)
+- SSH tunnel configuration for gateway access
+
+**Repositories:**
+
+- Infrastructure: [openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner)
+- Docker config: [openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config)
+
+This approach complements the Docker setup above with reproducible deployments, version-controlled infrastructure, and automated disaster recovery.
+
+> **Note:** Community-maintained. For issues or contributions, see the repository links above.

docs/install/installer.md

@@ -286,6 +286,14 @@ Designed for environments where you want everything under a local prefix (defaul
     & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
     ```
   </Tab>
+  <Tab title="Debug trace">
+    ```powershell
+    # install.ps1 has no dedicated -Verbose flag yet.
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+  </Tab>
 </Tabs>
 
 <AccordionGroup>
@@ -379,6 +387,18 @@ Use non-interactive flags/env vars for predictable runs.
     Run `npm config get prefix`, append `\bin`, add that directory to user PATH, then reopen PowerShell.
   </Accordion>
 
+  <Accordion title="Windows: how to get verbose installer output">
+    `install.ps1` does not currently expose a `-Verbose` switch.
+    Use PowerShell tracing for script-level diagnostics:
+
+    ```powershell
+    Set-PSDebug -Trace 1
+    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+    Set-PSDebug -Trace 0
+    ```
+
+  </Accordion>
+
   <Accordion title="openclaw not found after install">
     Usually a PATH issue. See [Node.js troubleshooting](/install/node#troubleshooting).
   </Accordion>

docs/nodes/audio.md

@@ -107,8 +107,27 @@ Note: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI
 - Transcript is available to templates as `{{Transcript}}`.
 - CLI stdout is capped (5MB); keep CLI output concise.
 
+## Mention Detection in Groups
+
+When `requireMention: true` is set for a group chat, OpenClaw now transcribes audio **before** checking for mentions. This allows voice notes to be processed even when they contain mentions.
+
+**How it works:**
+
+1. If a voice message has no text body and the group requires mentions, OpenClaw performs a "preflight" transcription.
+2. The transcript is checked for mention patterns (e.g., `@BotName`, emoji triggers).
+3. If a mention is found, the message proceeds through the full reply pipeline.
+4. The transcript is used for mention detection so voice notes can pass the mention gate.
+
+**Fallback behavior:**
+
+- If transcription fails during preflight (timeout, API error, etc.), the message is processed based on text-only mention detection.
+- This ensures that mixed messages (text + audio) are never incorrectly dropped.
+
+**Example:** A user sends a voice note saying "Hey @Claude, what's the weather?" in a Telegram group with `requireMention: true`. The voice note is transcribed, the mention is detected, and the agent replies.
+
 ## Gotchas
 
 - Scope rules use first-match wins. `chatType` is normalized to `direct`, `group`, or `room`.
 - Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.
 - Keep timeouts reasonable (`timeoutSeconds`, default 60s) to avoid blocking the reply queue.
+- Preflight transcription only processes the **first** audio attachment for mention detection. Additional audio is processed during the main media understanding phase.

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.9 \
+APP_VERSION=2026.2.13 \
 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.9.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.2.13.zip
 
 # Optional: also build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.9.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.2.13.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.9.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.9 \
+APP_VERSION=2026.2.13 \
 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.9.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.2.13.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.9.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.13.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.9.zip` (and `OpenClaw-2026.2.9.dSYM.zip`) to the GitHub release for tag `v2026.2.9`.
+- Upload `OpenClaw-2026.2.13.zip` (and `OpenClaw-2026.2.13.dSYM.zip`) to the GitHub release for tag `v2026.2.13`.
 - 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/providers/glm.md

@@ -9,7 +9,7 @@ title: "GLM Models"
 # GLM models
 
 GLM is a **model family** (not a company) available through the Z.AI platform. In OpenClaw, GLM
-models are accessed via the `zai` provider and model IDs like `zai/glm-4.7`.
+models are accessed via the `zai` provider and model IDs like `zai/glm-5`.
 
 ## CLI setup
 
@@ -22,12 +22,12 @@ openclaw onboard --auth-choice zai-api-key
 ```json5
 {
   env: { ZAI_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "zai/glm-4.7" } } },
+  agents: { defaults: { model: { primary: "zai/glm-5" } } },
 }
 ```
 
 ## Notes
 
 - GLM versions and availability can change; check Z.AI's docs for the latest.
-- Example model IDs include `glm-4.7` and `glm-4.6`.
+- Example model IDs include `glm-5`, `glm-4.7`, and `glm-4.6`.
 - For provider details, see [/providers/zai](/providers/zai).

docs/providers/index.md

@@ -39,6 +39,7 @@ See [Venice AI](/providers/venice).
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
 - [Qwen (OAuth)](/providers/qwen)
 - [OpenRouter](/providers/openrouter)
+- [LiteLLM (unified gateway)](/providers/litellm)
 - [Vercel AI Gateway](/providers/vercel-ai-gateway)
 - [Together AI](/providers/together)
 - [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)

docs/providers/litellm.md

@@ -0,0 +1,153 @@
+---
+summary: "Run OpenClaw through LiteLLM Proxy for unified model access and cost tracking"
+read_when:
+  - You want to route OpenClaw through a LiteLLM proxy
+  - You need cost tracking, logging, or model routing through LiteLLM
+---
+
+# LiteLLM
+
+[LiteLLM](https://litellm.ai) is an open-source LLM gateway that provides a unified API to 100+ model providers. Route OpenClaw through LiteLLM to get centralized cost tracking, logging, and the flexibility to switch backends without changing your OpenClaw config.
+
+## Why use LiteLLM with OpenClaw?
+
+- **Cost tracking** — See exactly what OpenClaw spends across all models
+- **Model routing** — Switch between Claude, GPT-4, Gemini, Bedrock without config changes
+- **Virtual keys** — Create keys with spend limits for OpenClaw
+- **Logging** — Full request/response logs for debugging
+- **Fallbacks** — Automatic failover if your primary provider is down
+
+## Quick start
+
+### Via onboarding
+
+```bash
+openclaw onboard --auth-choice litellm-api-key
+```
+
+### Manual setup
+
+1. Start LiteLLM Proxy:
+
+```bash
+pip install 'litellm[proxy]'
+litellm --model claude-opus-4-6
+```
+
+2. Point OpenClaw to LiteLLM:
+
+```bash
+export LITELLM_API_KEY="your-litellm-key"
+
+openclaw
+```
+
+That's it. OpenClaw now routes through LiteLLM.
+
+## Configuration
+
+### Environment variables
+
+```bash
+export LITELLM_API_KEY="sk-litellm-key"
+```
+
+### Config file
+
+```json5
+{
+  models: {
+    providers: {
+      litellm: {
+        baseUrl: "http://localhost:4000",
+        apiKey: "${LITELLM_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "claude-opus-4-6",
+            name: "Claude Opus 4.6",
+            reasoning: true,
+            input: ["text", "image"],
+            contextWindow: 200000,
+            maxTokens: 64000,
+          },
+          {
+            id: "gpt-4o",
+            name: "GPT-4o",
+            reasoning: false,
+            input: ["text", "image"],
+            contextWindow: 128000,
+            maxTokens: 8192,
+          },
+        ],
+      },
+    },
+  },
+  agents: {
+    defaults: {
+      model: { primary: "litellm/claude-opus-4-6" },
+    },
+  },
+}
+```
+
+## Virtual keys
+
+Create a dedicated key for OpenClaw with spend limits:
+
+```bash
+curl -X POST "http://localhost:4000/key/generate" \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key_alias": "openclaw",
+    "max_budget": 50.00,
+    "budget_duration": "monthly"
+  }'
+```
+
+Use the generated key as `LITELLM_API_KEY`.
+
+## Model routing
+
+LiteLLM can route model requests to different backends. Configure in your LiteLLM `config.yaml`:
+
+```yaml
+model_list:
+  - model_name: claude-opus-4-6
+    litellm_params:
+      model: claude-opus-4-6
+      api_key: os.environ/ANTHROPIC_API_KEY
+
+  - model_name: gpt-4o
+    litellm_params:
+      model: gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+```
+
+OpenClaw keeps requesting `claude-opus-4-6` — LiteLLM handles the routing.
+
+## Viewing usage
+
+Check LiteLLM's dashboard or API:
+
+```bash
+# Key info
+curl "http://localhost:4000/key/info" \
+  -H "Authorization: Bearer sk-litellm-key"
+
+# Spend logs
+curl "http://localhost:4000/spend/logs" \
+  -H "Authorization: Bearer $LITELLM_MASTER_KEY"
+```
+
+## Notes
+
+- LiteLLM runs on `http://localhost:4000` by default
+- OpenClaw connects via the OpenAI-compatible `/v1/chat/completions` endpoint
+- All OpenClaw features work through LiteLLM — no limitations
+
+## See also
+
+- [LiteLLM Docs](https://docs.litellm.ai)
+- [Model Providers](/concepts/model-providers)

docs/providers/together.md

@@ -27,7 +27,7 @@ openclaw onboard --auth-choice together-api-key
 {
   agents: {
     defaults: {
-      model: { primary: "together/zai-org/GLM-4.7" },
+      model: { primary: "together/moonshotai/Kimi-K2.5" },
     },
   },
 }
@@ -42,7 +42,7 @@ openclaw onboard --non-interactive \
   --together-api-key "$TOGETHER_API_KEY"
 ```
 
-This will set `together/zai-org/GLM-4.7` as the default model.
+This will set `together/moonshotai/Kimi-K2.5` as the default model.
 
 ## Environment note
 

docs/providers/zai.md

@@ -25,12 +25,12 @@ openclaw onboard --zai-api-key "$ZAI_API_KEY"
 ```json5
 {
   env: { ZAI_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "zai/glm-4.7" } } },
+  agents: { defaults: { model: { primary: "zai/glm-5" } } },
 }
 ```
 
 ## Notes
 
-- GLM models are available as `zai/<model>` (example: `zai/glm-4.7`).
+- GLM models are available as `zai/<model>` (example: `zai/glm-5`).
 - See [/providers/glm](/providers/glm) for the model family overview.
 - Z.AI uses Bearer auth with your API key.

docs/reference/transcript-hygiene.md

@@ -24,6 +24,7 @@ Scope includes:
 - Turn validation / ordering
 - Thought signature cleanup
 - Image payload sanitization
+- User-input provenance tagging (for inter-session routed prompts)
 
 If you need transcript storage details, see:
 
@@ -72,6 +73,23 @@ Implementation:
 
 ---
 
+## Global rule: inter-session input provenance
+
+When an agent sends a prompt into another session via `sessions_send` (including
+agent-to-agent reply/announce steps), OpenClaw persists the created user turn with:
+
+- `message.provenance.kind = "inter_session"`
+
+This metadata is written at transcript append time and does not change role
+(`role: "user"` remains for provider compatibility). Transcript readers can use
+this to avoid treating routed internal prompts as end-user-authored instructions.
+
+During context rebuild, OpenClaw also prepends a short `[Inter-session message]`
+marker to those user turns in-memory so the model can distinguish them from
+external end-user instructions.
+
+---
+
 ## Provider matrix (current behavior)
 
 **OpenAI / OpenAI Codex**

docs/start/getting-started.md

@@ -34,6 +34,11 @@ Check your Node version with `node --version` if you are unsure.
         ```bash
         curl -fsSL https://openclaw.ai/install.sh | bash
         ```
+        <img
+  src="/assets/install-script.svg"
+  alt="Install Script Process"
+  className="rounded-lg"
+/>
       </Tab>
       <Tab title="Windows (PowerShell)">
         ```powershell

docs/start/openclaw.md

@@ -34,22 +34,6 @@ Start conservative:
 You want this:
 
 ```mermaid
-%%{init: {
-  'theme': 'base',
-  'themeVariables': {
-    'primaryColor': '#ffffff',
-    'primaryTextColor': '#000000',
-    'primaryBorderColor': '#000000',
-    'lineColor': '#000000',
-    'secondaryColor': '#f9f9fb',
-    'tertiaryColor': '#ffffff',
-    'clusterBkg': '#f9f9fb',
-    'clusterBorder': '#000000',
-    'nodeBorder': '#000000',
-    'mainBkg': '#ffffff',
-    'edgeLabelBackground': '#ffffff'
-  }
-}}%%
 flowchart TB
     A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
     B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>Pi agent"]

docs/start/wizard-cli-automation.md

@@ -106,6 +106,23 @@ Add `--json` for a machine-readable summary.
       --gateway-bind loopback
     ```
   </Accordion>
+  <Accordion title="Custom provider example">
+    ```bash
+    openclaw onboard --non-interactive \
+      --mode local \
+      --auth-choice custom-api-key \
+      --custom-base-url "https://llm.example.com/v1" \
+      --custom-model-id "foo-large" \
+      --custom-api-key "$CUSTOM_API_KEY" \
+      --custom-provider-id "my-custom" \
+      --custom-compatibility anthropic \
+      --gateway-port 18789 \
+      --gateway-bind loopback
+    ```
+
+    `--custom-api-key` is optional. If omitted, onboarding checks `CUSTOM_API_KEY`.
+
+  </Accordion>
 </AccordionGroup>
 
 ## Add another agent

docs/start/wizard-cli-reference.md

@@ -175,6 +175,18 @@ What you set:
     Moonshot (Kimi K2) and Kimi Coding configs are auto-written.
     More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot).
   </Accordion>
+  <Accordion title="Custom provider">
+    Works with OpenAI-compatible and Anthropic-compatible endpoints.
+
+    Non-interactive flags:
+    - `--auth-choice custom-api-key`
+    - `--custom-base-url`
+    - `--custom-model-id`
+    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
+    - `--custom-provider-id` (optional)
+    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)
+
+  </Accordion>
   <Accordion title="Skip">
     Leaves auth unconfigured.
   </Accordion>

docs/tools/browser.md

@@ -192,6 +192,7 @@ Notes:
 Key ideas:
 
 - Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
+- If browser control is enabled and no auth is configured, OpenClaw auto-generates `gateway.auth.token` on startup and persists it to config.
 - Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.
 - Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.
 
@@ -315,6 +316,11 @@ For local integrations only, the Gateway exposes a small loopback HTTP API:
 
 All endpoints accept `?profile=<name>`.
 
+If gateway auth is configured, browser HTTP routes require auth too:
+
+- `Authorization: Bearer <gateway token>`
+- `x-openclaw-password: <gateway password>` or HTTP Basic auth with that password
+
 ### Playwright requirement
 
 Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require

docs/zh-CN/automation/hooks.md

@@ -48,12 +48,11 @@ hooks 系统允许你：
 
 ### 捆绑的 Hooks
 
-OpenClaw 附带四个自动发现的捆绑 hooks：
+OpenClaw 附带三个自动发现的捆绑 hooks：
 
 - **💾 session-memory**：当你发出 `/new` 时将会话上下文保存到智能体工作区（默认 `~/.openclaw/workspace/memory/`）
 - **📝 command-logger**：将所有命令事件记录到 `~/.openclaw/logs/commands.log`
 - **🚀 boot-md**：当 Gateway 网关启动时运行 `BOOT.md`（需要启用内部 hooks）
-- **😈 soul-evil**：在清除窗口期间或随机机会下将注入的 `SOUL.md` 内容替换为 `SOUL_EVIL.md`
 
 列出可用的 hooks：
 
@@ -533,42 +532,6 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 openclaw hooks enable command-logger
 ```
 
-### soul-evil
-
-在清除窗口期间或随机机会下将注入的 `SOUL.md` 内容替换为 `SOUL_EVIL.md`。
-
-**事件**：`agent:bootstrap`
-
-**文档**：[SOUL Evil Hook](/hooks/soul-evil)
-
-**输出**：不写入文件；替换仅在内存中发生。
-
-**启用**：
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-**配置**：
-
-```json
-{
-  "hooks": {
-    "internal": {
-      "enabled": true,
-      "entries": {
-        "soul-evil": {
-          "enabled": true,
-          "file": "SOUL_EVIL.md",
-          "chance": 0.1,
-          "purge": { "at": "21:00", "duration": "15m" }
-        }
-      }
-    }
-  }
-}
-```
-
 ### boot-md
 
 当 Gateway 网关启动时运行 `BOOT.md`（在渠道启动之后）。

docs/zh-CN/cli/hooks.md

@@ -39,13 +39,12 @@ openclaw hooks list
 **示例输出：**
 
 ```
-Hooks (4/4 ready)
+Hooks (3/3 ready)
 
 Ready:
   🚀 boot-md ✓ - Run BOOT.md on gateway startup
   📝 command-logger ✓ - Log all command events to a centralized audit file
   💾 session-memory ✓ - Save session context to memory when /new command is issued
-  😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
 ```
 
 **示例（详细模式）：**
@@ -284,18 +283,6 @@ grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
 
 **参见：** [command-logger 文档](/automation/hooks#command-logger)
 
-### soul-evil
-
-在清除窗口期间或随机情况下，将注入的 `SOUL.md` 内容替换为 `SOUL_EVIL.md`。
-
-**启用：**
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-**参见：** [SOUL Evil 钩子](/hooks/soul-evil)
-
 ### boot-md
 
 在 Gateway 网关启动时（渠道启动后）运行 `BOOT.md`。

docs/zh-CN/hooks/soul-evil.md

@@ -1,72 +0,0 @@
----
-read_when:
-  - 你想要启用或调整 SOUL Evil 钩子
-  - 你想要设置清除窗口或随机概率的人格替换
-summary: SOUL Evil 钩子（将 SOUL.md 替换为 SOUL_EVIL.md）
-title: SOUL Evil 钩子
-x-i18n:
-  generated_at: "2026-02-01T20:42:18Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: cc32c1e207f2b6923a6ede8299293f8fc07f3c8d6b2a377775237c0173fe8d1b
-  source_path: hooks/soul-evil.md
-  workflow: 14
----
-
-# SOUL Evil 钩子
-
-SOUL Evil 钩子在清除窗口期间或随机概率下，将**注入的** `SOUL.md` 内容替换为 `SOUL_EVIL.md`。它**不会**修改磁盘上的文件。
-
-## 工作原理
-
-当 `agent:bootstrap` 运行时，该钩子可以在系统提示词组装之前，在内存中替换 `SOUL.md` 的内容。如果 `SOUL_EVIL.md` 缺失或为空，OpenClaw 会记录警告并保留正常的 `SOUL.md`。
-
-子智能体运行**不会**在其引导文件中包含 `SOUL.md`，因此此钩子对子智能体没有影响。
-
-## 启用
-
-```bash
-openclaw hooks enable soul-evil
-```
-
-然后设置配置：
-
-```json
-{
-  "hooks": {
-    "internal": {
-      "enabled": true,
-      "entries": {
-        "soul-evil": {
-          "enabled": true,
-          "file": "SOUL_EVIL.md",
-          "chance": 0.1,
-          "purge": { "at": "21:00", "duration": "15m" }
-        }
-      }
-    }
-  }
-}
-```
-
-在智能体工作区根目录（`SOUL.md` 旁边）创建 `SOUL_EVIL.md`。
-
-## 选项
-
-- `file`（字符串）：替代的 SOUL 文件名（默认：`SOUL_EVIL.md`）
-- `chance`（数字 0–1）：每次运行使用 `SOUL_EVIL.md` 的随机概率
-- `purge.at`（HH:mm）：每日清除开始时间（24 小时制）
-- `purge.duration`（时长）：窗口长度（例如 `30s`、`10m`、`1h`）
-
-**优先级：** 清除窗口优先于随机概率。
-
-**时区：** 设置了 `agents.defaults.userTimezone` 时使用该时区；否则使用主机时区。
-
-## 注意事项
-
-- 不会在磁盘上写入或修改任何文件。
-- 如果 `SOUL.md` 不在引导列表中，该钩子不执行任何操作。
-
-## 另请参阅
-
-- [钩子](/automation/hooks)

extensions/bluebubbles/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/bluebubbles",
-  "version": "2026.2.9",
+  "version": "2026.2.12",
   "description": "OpenClaw BlueBubbles channel plugin",
   "type": "module",
   "devDependencies": {

extensions/bluebubbles/src/monitor.test.ts

@@ -254,9 +254,20 @@ function createMockRequest(
   body: unknown,
   headers: Record<string, string> = {},
 ): IncomingMessage {
+  const parsedUrl = new URL(url, "http://localhost");
+  const hasAuthQuery = parsedUrl.searchParams.has("guid") || parsedUrl.searchParams.has("password");
+  const hasAuthHeader =
+    headers["x-guid"] !== undefined ||
+    headers["x-password"] !== undefined ||
+    headers["x-bluebubbles-guid"] !== undefined ||
+    headers.authorization !== undefined;
+  if (!hasAuthQuery && !hasAuthHeader) {
+    parsedUrl.searchParams.set("password", "test-password");
+  }
+
   const req = new EventEmitter() as IncomingMessage;
   req.method = method;
-  req.url = url;
+  req.url = `${parsedUrl.pathname}${parsedUrl.search}`;
   req.headers = headers;
   (req as unknown as { socket: { remoteAddress: string } }).socket = { remoteAddress: "127.0.0.1" };
 
@@ -546,40 +557,41 @@ describe("BlueBubbles webhook monitor", () => {
       expect(res.statusCode).toBe(401);
     });
 
-    it("allows localhost requests without authentication", async () => {
+    it("requires authentication for loopback requests when password is configured", async () => {
       const account = createMockAccount({ password: "secret-token" });
       const config: OpenClawConfig = {};
       const core = createMockRuntime();
       setBlueBubblesRuntime(core);
+      for (const remoteAddress of ["127.0.0.1", "::1", "::ffff:127.0.0.1"]) {
+        const req = createMockRequest("POST", "/bluebubbles-webhook", {
+          type: "new-message",
+          data: {
+            text: "hello",
+            handle: { address: "+15551234567" },
+            isGroup: false,
+            isFromMe: false,
+            guid: "msg-1",
+          },
+        });
+        (req as unknown as { socket: { remoteAddress: string } }).socket = {
+          remoteAddress,
+        };
 
-      const req = createMockRequest("POST", "/bluebubbles-webhook", {
-        type: "new-message",
-        data: {
-          text: "hello",
-          handle: { address: "+15551234567" },
-          isGroup: false,
-          isFromMe: false,
-          guid: "msg-1",
-        },
-      });
-      // Localhost address
-      (req as unknown as { socket: { remoteAddress: string } }).socket = {
-        remoteAddress: "127.0.0.1",
-      };
+        const loopbackUnregister = registerBlueBubblesWebhookTarget({
+          account,
+          config,
+          runtime: { log: vi.fn(), error: vi.fn() },
+          core,
+          path: "/bluebubbles-webhook",
+        });
 
-      unregister = registerBlueBubblesWebhookTarget({
-        account,
-        config,
-        runtime: { log: vi.fn(), error: vi.fn() },
-        core,
-        path: "/bluebubbles-webhook",
-      });
+        const res = createMockResponse();
+        const handled = await handleBlueBubblesWebhookRequest(req, res);
+        expect(handled).toBe(true);
+        expect(res.statusCode).toBe(401);
 
-      const res = createMockResponse();
-      const handled = await handleBlueBubblesWebhookRequest(req, res);
-
-      expect(handled).toBe(true);
-      expect(res.statusCode).toBe(200);
+        loopbackUnregister();
+      }
     });
 
     it("ignores unregistered webhook paths", async () => {

extensions/bluebubbles/src/monitor.ts

@@ -1533,10 +1533,6 @@ export async function handleBlueBubblesWebhookRequest(
     if (guid && guid.trim() === token) {
       return true;
     }
-    const remote = req.socket?.remoteAddress ?? "";
-    if (remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1") {
-      return true;
-    }
     return false;
   });
 

extensions/copilot-proxy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/copilot-proxy",
-  "version": "2026.2.9",
+  "version": "2026.2.12",
   "private": true,
   "description": "OpenClaw Copilot Proxy provider plugin",
   "type": "module",

extensions/diagnostics-otel/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@openclaw/diagnostics-otel",
-  "version": "2026.2.9",
+  "version": "2026.2.12",
   "description": "OpenClaw diagnostics OpenTelemetry exporter",
   "type": "module",
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/api-logs": "^0.211.0",
-    "@opentelemetry/exporter-logs-otlp-http": "^0.211.0",
-    "@opentelemetry/exporter-metrics-otlp-http": "^0.211.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",
-    "@opentelemetry/resources": "^2.5.0",
-    "@opentelemetry/sdk-logs": "^0.211.0",
-    "@opentelemetry/sdk-metrics": "^2.5.0",
-    "@opentelemetry/sdk-node": "^0.211.0",
-    "@opentelemetry/sdk-trace-base": "^2.5.0",
+    "@opentelemetry/api-logs": "^0.212.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.212.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.212.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.212.0",
+    "@opentelemetry/resources": "^2.5.1",
+    "@opentelemetry/sdk-logs": "^0.212.0",
+    "@opentelemetry/sdk-metrics": "^2.5.1",
+    "@opentelemetry/sdk-node": "^0.212.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.1",
     "@opentelemetry/semantic-conventions": "^1.39.0"
   },
   "devDependencies": {

extensions/discord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/discord",
-  "version": "2026.2.9",
+  "version": "2026.2.12",
   "description": "OpenClaw Discord channel plugin",
   "type": "module",
   "devDependencies": {

extensions/feishu/package.json

@@ -1,16 +1,13 @@
 {
   "name": "@openclaw/feishu",
-  "version": "2026.2.9",
+  "version": "2026.2.12",
   "description": "OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng)",
   "type": "module",
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.58.0",
+    "@larksuiteoapi/node-sdk": "^1.59.0",
     "@sinclair/typebox": "0.34.48",
     "zod": "^4.3.6"
   },
-  "devDependencies": {
-    "openclaw": "workspace:*"
-  },
   "openclaw": {
     "extensions": [
       "./index.ts"

extensions/feishu/src/bot.checkBotMentioned.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { parseFeishuMessageEvent } from "./bot.js";
+
+// Helper to build a minimal FeishuMessageEvent for testing
+function makeEvent(
+  chatType: "p2p" | "group",
+  mentions?: Array<{ key: string; name: string; id: { open_id?: string } }>,
+) {
+  return {
+    sender: {
+      sender_id: { user_id: "u1", open_id: "ou_sender" },
+    },
+    message: {
+      message_id: "msg_1",
+      chat_id: "oc_chat1",
+      chat_type: chatType,
+      message_type: "text",
+      content: JSON.stringify({ text: "hello" }),
+      mentions,
+    },
+  };
+}
+
+describe("parseFeishuMessageEvent – mentionedBot", () => {
+  const BOT_OPEN_ID = "ou_bot_123";
+
+  it("returns mentionedBot=false when there are no mentions", () => {
+    const event = makeEvent("group", []);
+    const ctx = parseFeishuMessageEvent(event as any, BOT_OPEN_ID);
+    expect(ctx.mentionedBot).toBe(false);
+  });
+
+  it("returns mentionedBot=true when bot is mentioned", () => {
+    const event = makeEvent("group", [
+      { key: "@_user_1", name: "Bot", id: { open_id: BOT_OPEN_ID } },
+    ]);
+    const ctx = parseFeishuMessageEvent(event as any, BOT_OPEN_ID);
+    expect(ctx.mentionedBot).toBe(true);
+  });
+
+  it("returns mentionedBot=false when only other users are mentioned", () => {
+    const event = makeEvent("group", [
+      { key: "@_user_1", name: "Alice", id: { open_id: "ou_alice" } },
+    ]);
+    const ctx = parseFeishuMessageEvent(event as any, BOT_OPEN_ID);
+    expect(ctx.mentionedBot).toBe(false);
+  });
+
+  it("returns mentionedBot=false when botOpenId is undefined (unknown bot)", () => {
+    const event = makeEvent("group", [
+      { key: "@_user_1", name: "Alice", id: { open_id: "ou_alice" } },
+    ]);
+    const ctx = parseFeishuMessageEvent(event as any, undefined);
+    expect(ctx.mentionedBot).toBe(false);
+  });
+
+  it("returns mentionedBot=false when botOpenId is empty string (probe failed)", () => {
+    const event = makeEvent("group", [
+      { key: "@_user_1", name: "Alice", id: { open_id: "ou_alice" } },
+    ]);
+    const ctx = parseFeishuMessageEvent(event as any, "");
+    expect(ctx.mentionedBot).toBe(false);
+  });
+});

extensions/feishu/src/bot.test.ts

@@ -0,0 +1,265 @@
+import type { ClawdbotConfig, PluginRuntime, RuntimeEnv } from "openclaw/plugin-sdk";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { FeishuMessageEvent } from "./bot.js";
+import { handleFeishuMessage } from "./bot.js";
+import { setFeishuRuntime } from "./runtime.js";
+
+const { mockCreateFeishuReplyDispatcher, mockSendMessageFeishu, mockGetMessageFeishu } = vi.hoisted(
+  () => ({
+    mockCreateFeishuReplyDispatcher: vi.fn(() => ({
+      dispatcher: vi.fn(),
+      replyOptions: {},
+      markDispatchIdle: vi.fn(),
+    })),
+    mockSendMessageFeishu: vi.fn().mockResolvedValue({ messageId: "pairing-msg", chatId: "oc-dm" }),
+    mockGetMessageFeishu: vi.fn().mockResolvedValue(null),
+  }),
+);
+
+vi.mock("./reply-dispatcher.js", () => ({
+  createFeishuReplyDispatcher: mockCreateFeishuReplyDispatcher,
+}));
+
+vi.mock("./send.js", () => ({
+  sendMessageFeishu: mockSendMessageFeishu,
+  getMessageFeishu: mockGetMessageFeishu,
+}));
+
+describe("handleFeishuMessage command authorization", () => {
+  const mockFinalizeInboundContext = vi.fn((ctx: unknown) => ctx);
+  const mockDispatchReplyFromConfig = vi
+    .fn()
+    .mockResolvedValue({ queuedFinal: false, counts: { final: 1 } });
+  const mockResolveCommandAuthorizedFromAuthorizers = vi.fn(() => false);
+  const mockShouldComputeCommandAuthorized = vi.fn(() => true);
+  const mockReadAllowFromStore = vi.fn().mockResolvedValue([]);
+  const mockUpsertPairingRequest = vi.fn().mockResolvedValue({ code: "ABCDEFGH", created: false });
+  const mockBuildPairingReply = vi.fn(() => "Pairing response");
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setFeishuRuntime({
+      system: {
+        enqueueSystemEvent: vi.fn(),
+      },
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "main",
+            accountId: "default",
+            sessionKey: "agent:main:feishu:dm:ou-attacker",
+            matchedBy: "default",
+          })),
+        },
+        reply: {
+          resolveEnvelopeFormatOptions: vi.fn(() => ({ template: "channel+name+time" })),
+          formatAgentEnvelope: vi.fn((params: { body: string }) => params.body),
+          finalizeInboundContext: mockFinalizeInboundContext,
+          dispatchReplyFromConfig: mockDispatchReplyFromConfig,
+        },
+        commands: {
+          shouldComputeCommandAuthorized: mockShouldComputeCommandAuthorized,
+          resolveCommandAuthorizedFromAuthorizers: mockResolveCommandAuthorizedFromAuthorizers,
+        },
+        pairing: {
+          readAllowFromStore: mockReadAllowFromStore,
+          upsertPairingRequest: mockUpsertPairingRequest,
+          buildPairingReply: mockBuildPairingReply,
+        },
+      },
+    } as unknown as PluginRuntime);
+  });
+
+  it("uses authorizer resolution instead of hardcoded CommandAuthorized=true", async () => {
+    const cfg: ClawdbotConfig = {
+      commands: { useAccessGroups: true },
+      channels: {
+        feishu: {
+          dmPolicy: "open",
+          allowFrom: ["ou-admin"],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-attacker",
+        },
+      },
+      message: {
+        message_id: "msg-auth-bypass-regression",
+        chat_id: "oc-dm",
+        chat_type: "p2p",
+        message_type: "text",
+        content: JSON.stringify({ text: "/status" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: { log: vi.fn(), error: vi.fn() } as RuntimeEnv,
+    });
+
+    expect(mockResolveCommandAuthorizedFromAuthorizers).toHaveBeenCalledWith({
+      useAccessGroups: true,
+      authorizers: [{ configured: true, allowed: false }],
+    });
+    expect(mockFinalizeInboundContext).toHaveBeenCalledTimes(1);
+    expect(mockFinalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        CommandAuthorized: false,
+        SenderId: "ou-attacker",
+        Surface: "feishu",
+      }),
+    );
+  });
+
+  it("reads pairing allow store for non-command DMs when dmPolicy is pairing", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+    mockReadAllowFromStore.mockResolvedValue(["ou-attacker"]);
+
+    const cfg: ClawdbotConfig = {
+      commands: { useAccessGroups: true },
+      channels: {
+        feishu: {
+          dmPolicy: "pairing",
+          allowFrom: [],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-attacker",
+        },
+      },
+      message: {
+        message_id: "msg-read-store-non-command",
+        chat_id: "oc-dm",
+        chat_type: "p2p",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello there" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: { log: vi.fn(), error: vi.fn() } as RuntimeEnv,
+    });
+
+    expect(mockReadAllowFromStore).toHaveBeenCalledWith("feishu");
+    expect(mockResolveCommandAuthorizedFromAuthorizers).not.toHaveBeenCalled();
+    expect(mockFinalizeInboundContext).toHaveBeenCalledTimes(1);
+    expect(mockDispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it("creates pairing request and drops unauthorized DMs in pairing mode", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(false);
+    mockReadAllowFromStore.mockResolvedValue([]);
+    mockUpsertPairingRequest.mockResolvedValue({ code: "ABCDEFGH", created: true });
+
+    const cfg: ClawdbotConfig = {
+      channels: {
+        feishu: {
+          dmPolicy: "pairing",
+          allowFrom: [],
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-unapproved",
+        },
+      },
+      message: {
+        message_id: "msg-pairing-flow",
+        chat_id: "oc-dm",
+        chat_type: "p2p",
+        message_type: "text",
+        content: JSON.stringify({ text: "hello" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: { log: vi.fn(), error: vi.fn() } as RuntimeEnv,
+    });
+
+    expect(mockUpsertPairingRequest).toHaveBeenCalledWith({
+      channel: "feishu",
+      id: "ou-unapproved",
+      meta: { name: undefined },
+    });
+    expect(mockBuildPairingReply).toHaveBeenCalledWith({
+      channel: "feishu",
+      idLine: "Your Feishu user id: ou-unapproved",
+      code: "ABCDEFGH",
+    });
+    expect(mockSendMessageFeishu).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: "user:ou-unapproved",
+        accountId: "default",
+      }),
+    );
+    expect(mockFinalizeInboundContext).not.toHaveBeenCalled();
+    expect(mockDispatchReplyFromConfig).not.toHaveBeenCalled();
+  });
+
+  it("computes group command authorization from group allowFrom", async () => {
+    mockShouldComputeCommandAuthorized.mockReturnValue(true);
+    mockResolveCommandAuthorizedFromAuthorizers.mockReturnValue(false);
+
+    const cfg: ClawdbotConfig = {
+      commands: { useAccessGroups: true },
+      channels: {
+        feishu: {
+          groups: {
+            "oc-group": {
+              requireMention: false,
+            },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    const event: FeishuMessageEvent = {
+      sender: {
+        sender_id: {
+          open_id: "ou-attacker",
+        },
+      },
+      message: {
+        message_id: "msg-group-command-auth",
+        chat_id: "oc-group",
+        chat_type: "group",
+        message_type: "text",
+        content: JSON.stringify({ text: "/status" }),
+      },
+    };
+
+    await handleFeishuMessage({
+      cfg,
+      event,
+      runtime: { log: vi.fn(), error: vi.fn() } as RuntimeEnv,
+    });
+
+    expect(mockResolveCommandAuthorizedFromAuthorizers).toHaveBeenCalledWith({
+      useAccessGroups: true,
+      authorizers: [{ configured: false, allowed: false }],
+    });
+    expect(mockFinalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ChatType: "group",
+        CommandAuthorized: false,
+        SenderId: "ou-attacker",
+      }),
+    );
+  });
+});

extensions/feishu/src/bot.ts

@@ -21,7 +21,7 @@ import {
 } from "./policy.js";
 import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
 import { getFeishuRuntime } from "./runtime.js";
-import { getMessageFeishu } from "./send.js";
+import { getMessageFeishu, sendMessageFeishu } from "./send.js";
 
 // --- Message deduplication ---
 // Prevent duplicate processing when WebSocket reconnects or Feishu redelivers messages.
@@ -216,7 +216,7 @@ function parseMessageContent(content: string, messageType: string): string {
 function checkBotMentioned(event: FeishuMessageEvent, botOpenId?: string): boolean {
   const mentions = event.message.mentions ?? [];
   if (mentions.length === 0) return false;
-  if (!botOpenId) return mentions.length > 0;
+  if (!botOpenId) return false;
   return mentions.some((m) => m.id.open_id === botOpenId);
 }
 
@@ -581,12 +581,17 @@ export async function handleFeishuMessage(params: {
     0,
     feishuCfg?.historyLimit ?? cfg.messages?.groupChat?.historyLimit ?? DEFAULT_GROUP_HISTORY_LIMIT,
   );
+  const groupConfig = isGroup
+    ? resolveFeishuGroupConfig({ cfg: feishuCfg, groupId: ctx.chatId })
+    : undefined;
+  const dmPolicy = feishuCfg?.dmPolicy ?? "pairing";
+  const configAllowFrom = feishuCfg?.allowFrom ?? [];
+  const useAccessGroups = cfg.commands?.useAccessGroups !== false;
 
   if (isGroup) {
     const groupPolicy = feishuCfg?.groupPolicy ?? "open";
     const groupAllowFrom = feishuCfg?.groupAllowFrom ?? [];
     // DEBUG: log(`feishu[${account.accountId}]: groupPolicy=${groupPolicy}`);
-    const groupConfig = resolveFeishuGroupConfig({ cfg: feishuCfg, groupId: ctx.chatId });
 
     // Check if this GROUP is allowed (groupAllowFrom contains group IDs like oc_xxx, not user IDs)
     const groupAllowed = isFeishuGroupAllowed({
@@ -642,23 +647,73 @@ export async function handleFeishuMessage(params: {
       return;
     }
   } else {
-    const dmPolicy = feishuCfg?.dmPolicy ?? "pairing";
-    const allowFrom = feishuCfg?.allowFrom ?? [];
-
-    if (dmPolicy === "allowlist") {
-      const match = resolveFeishuAllowlistMatch({
-        allowFrom,
-        senderId: ctx.senderOpenId,
-      });
-      if (!match.allowed) {
-        log(`feishu[${account.accountId}]: sender ${ctx.senderOpenId} not in DM allowlist`);
-        return;
-      }
-    }
   }
 
   try {
     const core = getFeishuRuntime();
+    const shouldComputeCommandAuthorized = core.channel.commands.shouldComputeCommandAuthorized(
+      ctx.content,
+      cfg,
+    );
+    const storeAllowFrom =
+      !isGroup && (dmPolicy !== "open" || shouldComputeCommandAuthorized)
+        ? await core.channel.pairing.readAllowFromStore("feishu").catch(() => [])
+        : [];
+    const effectiveDmAllowFrom = [...configAllowFrom, ...storeAllowFrom];
+    const dmAllowed = resolveFeishuAllowlistMatch({
+      allowFrom: effectiveDmAllowFrom,
+      senderId: ctx.senderOpenId,
+      senderName: ctx.senderName,
+    }).allowed;
+
+    if (!isGroup && dmPolicy !== "open" && !dmAllowed) {
+      if (dmPolicy === "pairing") {
+        const { code, created } = await core.channel.pairing.upsertPairingRequest({
+          channel: "feishu",
+          id: ctx.senderOpenId,
+          meta: { name: ctx.senderName },
+        });
+        if (created) {
+          log(`feishu[${account.accountId}]: pairing request sender=${ctx.senderOpenId}`);
+          try {
+            await sendMessageFeishu({
+              cfg,
+              to: `user:${ctx.senderOpenId}`,
+              text: core.channel.pairing.buildPairingReply({
+                channel: "feishu",
+                idLine: `Your Feishu user id: ${ctx.senderOpenId}`,
+                code,
+              }),
+              accountId: account.accountId,
+            });
+          } catch (err) {
+            log(
+              `feishu[${account.accountId}]: pairing reply failed for ${ctx.senderOpenId}: ${String(err)}`,
+            );
+          }
+        }
+      } else {
+        log(
+          `feishu[${account.accountId}]: blocked unauthorized sender ${ctx.senderOpenId} (dmPolicy=${dmPolicy})`,
+        );
+      }
+      return;
+    }
+
+    const commandAllowFrom = isGroup ? (groupConfig?.allowFrom ?? []) : effectiveDmAllowFrom;
+    const senderAllowedForCommands = resolveFeishuAllowlistMatch({
+      allowFrom: commandAllowFrom,
+      senderId: ctx.senderOpenId,
+      senderName: ctx.senderName,
+    }).allowed;
+    const commandAuthorized = shouldComputeCommandAuthorized
+      ? core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+          useAccessGroups,
+          authorizers: [
+            { configured: commandAllowFrom.length > 0, allowed: senderAllowedForCommands },
+          ],
+        })
+      : undefined;
 
     // In group chats, the session is scoped to the group, but the *speaker* is the sender.
     // Using a group-scoped From causes the agent to treat different users as the same person.
@@ -815,7 +870,7 @@ export async function handleFeishuMessage(params: {
         MessageSid: `${ctx.messageId}:permission-error`,
         Timestamp: Date.now(),
         WasMentioned: false,
-        CommandAuthorized: true,
+        CommandAuthorized: commandAuthorized,
         OriginatingChannel: "feishu" as const,
         OriginatingTo: feishuTo,
       });
@@ -903,7 +958,7 @@ export async function handleFeishuMessage(params: {
       ReplyToBody: quotedContent ?? undefined,
       Timestamp: Date.now(),
       WasMentioned: ctx.mentionedBot,
-      CommandAuthorized: true,
+      CommandAuthorized: commandAuthorized,
       OriginatingChannel: "feishu" as const,
       OriginatingTo: feishuTo,
       ...mediaPayload,

extensions/feishu/src/channel.test.ts

@@ -0,0 +1,48 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { describe, expect, it, vi } from "vitest";
+
+const probeFeishuMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./probe.js", () => ({
+  probeFeishu: probeFeishuMock,
+}));
+
+import { feishuPlugin } from "./channel.js";
+
+describe("feishuPlugin.status.probeAccount", () => {
+  it("uses current account credentials for multi-account config", async () => {
+    const cfg = {
+      channels: {
+        feishu: {
+          enabled: true,
+          accounts: {
+            main: {
+              appId: "cli_main",
+              appSecret: "secret_main",
+              enabled: true,
+            },
+          },
+        },
+      },
+    } as OpenClawConfig;
+
+    const account = feishuPlugin.config.resolveAccount(cfg, "main");
+    probeFeishuMock.mockResolvedValueOnce({ ok: true, appId: "cli_main" });
+
+    const result = await feishuPlugin.status?.probeAccount?.({
+      account,
+      timeoutMs: 1_000,
+      cfg,
+    });
+
+    expect(probeFeishuMock).toHaveBeenCalledTimes(1);
+    expect(probeFeishuMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "main",
+        appId: "cli_main",
+        appSecret: "secret_main",
+      }),
+    );
+    expect(result).toMatchObject({ ok: true, appId: "cli_main" });
+  });
+});

extensions/feishu/src/channel.ts

@@ -321,9 +321,7 @@ export const feishuPlugin: ChannelPlugin<ResolvedFeishuAccount> = {
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
-    probeAccount: async ({ account }) => {
-      return await probeFeishu(account);
-    },
+    probeAccount: async ({ account }) => await probeFeishu(account),
     buildAccountSnapshot: ({ account, runtime, probe }) => ({
       accountId: account.accountId,
       enabled: account.enabled,

extensions/feishu/src/config-schema.ts

@@ -36,6 +36,10 @@ const MarkdownConfigSchema = z
 // Message render mode: auto (default) = detect markdown, raw = plain text, card = always card
 const RenderModeSchema = z.enum(["auto", "raw", "card"]).optional();
 
+// Streaming card mode: when enabled, card replies use Feishu's Card Kit streaming API
+// for incremental text display with a "Thinking..." placeholder
+const StreamingModeSchema = z.boolean().optional();
+
 const BlockStreamingCoalesceSchema = z
   .object({
     enabled: z.boolean().optional(),
@@ -142,6 +146,7 @@ export const FeishuAccountConfigSchema = z
     mediaMaxMb: z.number().positive().optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
     renderMode: RenderModeSchema,
+    streaming: StreamingModeSchema, // Enable streaming card mode (default: true)
     tools: FeishuToolsConfigSchema,
   })
   .strict();
@@ -177,6 +182,7 @@ export const FeishuConfigSchema = z
     mediaMaxMb: z.number().positive().optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
     renderMode: RenderModeSchema, // raw = plain text (default), card = interactive card with markdown
+    streaming: StreamingModeSchema, // Enable streaming card mode (default: true)
     tools: FeishuToolsConfigSchema,
     // Dynamic agent creation for DM users
     dynamicAgentCreation: DynamicAgentCreationSchema,

extensions/feishu/src/docx.ts

@@ -92,6 +92,14 @@ async function convertMarkdown(client: Lark.Client, markdown: string) {
   };
 }
 
+function sortBlocksByFirstLevel(blocks: any[], firstLevelIds: string[]): any[] {
+  if (!firstLevelIds || firstLevelIds.length === 0) return blocks;
+  const sorted = firstLevelIds.map((id) => blocks.find((b) => b.block_id === id)).filter(Boolean);
+  const sortedIds = new Set(firstLevelIds);
+  const remaining = blocks.filter((b) => !sortedIds.has(b.block_id));
+  return [...sorted, ...remaining];
+}
+
 /* eslint-disable @typescript-eslint/no-explicit-any -- SDK block types */
 async function insertBlocks(
   client: Lark.Client,
@@ -279,12 +287,13 @@ async function createDoc(client: Lark.Client, title: string, folderToken?: strin
 async function writeDoc(client: Lark.Client, docToken: string, markdown: string) {
   const deleted = await clearDocumentContent(client, docToken);
 
-  const { blocks } = await convertMarkdown(client, markdown);
+  const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
   if (blocks.length === 0) {
     return { success: true, blocks_deleted: deleted, blocks_added: 0, images_processed: 0 };
   }
+  const sortedBlocks = sortBlocksByFirstLevel(blocks, firstLevelBlockIds);
 
-  const { children: inserted, skipped } = await insertBlocks(client, docToken, blocks);
+  const { children: inserted, skipped } = await insertBlocks(client, docToken, sortedBlocks);
   const imagesProcessed = await processImages(client, docToken, markdown, inserted);
 
   return {
@@ -299,12 +308,13 @@ async function writeDoc(client: Lark.Client, docToken: string, markdown: string)
 }
 
 async function appendDoc(client: Lark.Client, docToken: string, markdown: string) {
-  const { blocks } = await convertMarkdown(client, markdown);
+  const { blocks, firstLevelBlockIds } = await convertMarkdown(client, markdown);
   if (blocks.length === 0) {
     throw new Error("Content is empty");
   }
+  const sortedBlocks = sortBlocksByFirstLevel(blocks, firstLevelBlockIds);
 
-  const { children: inserted, skipped } = await insertBlocks(client, docToken, blocks);
+  const { children: inserted, skipped } = await insertBlocks(client, docToken, sortedBlocks);
   const imagesProcessed = await processImages(client, docToken, markdown, inserted);
 
   return {

extensions/feishu/src/media.test.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+const resolveFeishuAccountMock = vi.hoisted(() => vi.fn());
+const normalizeFeishuTargetMock = vi.hoisted(() => vi.fn());
+const resolveReceiveIdTypeMock = vi.hoisted(() => vi.fn());
+
+const fileCreateMock = vi.hoisted(() => vi.fn());
+const messageCreateMock = vi.hoisted(() => vi.fn());
+const messageReplyMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./client.js", () => ({
+  createFeishuClient: createFeishuClientMock,
+}));
+
+vi.mock("./accounts.js", () => ({
+  resolveFeishuAccount: resolveFeishuAccountMock,
+}));
+
+vi.mock("./targets.js", () => ({
+  normalizeFeishuTarget: normalizeFeishuTargetMock,
+  resolveReceiveIdType: resolveReceiveIdTypeMock,
+}));
+
+import { sendMediaFeishu } from "./media.js";
+
+describe("sendMediaFeishu msg_type routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    resolveFeishuAccountMock.mockReturnValue({
+      configured: true,
+      accountId: "main",
+      appId: "app_id",
+      appSecret: "app_secret",
+      domain: "feishu",
+    });
+
+    normalizeFeishuTargetMock.mockReturnValue("ou_target");
+    resolveReceiveIdTypeMock.mockReturnValue("open_id");
+
+    createFeishuClientMock.mockReturnValue({
+      im: {
+        file: {
+          create: fileCreateMock,
+        },
+        message: {
+          create: messageCreateMock,
+          reply: messageReplyMock,
+        },
+      },
+    });
+
+    fileCreateMock.mockResolvedValue({
+      code: 0,
+      data: { file_key: "file_key_1" },
+    });
+
+    messageCreateMock.mockResolvedValue({
+      code: 0,
+      data: { message_id: "msg_1" },
+    });
+
+    messageReplyMock.mockResolvedValue({
+      code: 0,
+      data: { message_id: "reply_1" },
+    });
+  });
+
+  it("uses msg_type=media for mp4", async () => {
+    await sendMediaFeishu({
+      cfg: {} as any,
+      to: "user:ou_target",
+      mediaBuffer: Buffer.from("video"),
+      fileName: "clip.mp4",
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ file_type: "mp4" }),
+      }),
+    );
+
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "media" }),
+      }),
+    );
+  });
+
+  it("uses msg_type=media for opus", async () => {
+    await sendMediaFeishu({
+      cfg: {} as any,
+      to: "user:ou_target",
+      mediaBuffer: Buffer.from("audio"),
+      fileName: "voice.opus",
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ file_type: "opus" }),
+      }),
+    );
+
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "media" }),
+      }),
+    );
+  });
+
+  it("uses msg_type=file for documents", async () => {
+    await sendMediaFeishu({
+      cfg: {} as any,
+      to: "user:ou_target",
+      mediaBuffer: Buffer.from("doc"),
+      fileName: "paper.pdf",
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ file_type: "pdf" }),
+      }),
+    );
+
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "file" }),
+      }),
+    );
+  });
+
+  it("uses msg_type=media when replying with mp4", async () => {
+    await sendMediaFeishu({
+      cfg: {} as any,
+      to: "user:ou_target",
+      mediaBuffer: Buffer.from("video"),
+      fileName: "reply.mp4",
+      replyToMessageId: "om_parent",
+    });
+
+    expect(messageReplyMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: { message_id: "om_parent" },
+        data: expect.objectContaining({ msg_type: "media" }),
+      }),
+    );
+
+    expect(messageCreateMock).not.toHaveBeenCalled();
+  });
+});

extensions/feishu/src/media.ts

@@ -210,15 +210,16 @@ export async function uploadImageFeishu(params: {
 
   const client = createFeishuClient(account);
 
-  // SDK expects a Readable stream, not a Buffer
-  // Use type assertion since SDK actually accepts any Readable at runtime
-  const imageStream = typeof image === "string" ? fs.createReadStream(image) : Readable.from(image);
+  // SDK accepts Buffer directly or fs.ReadStream for file paths
+  // Using Readable.from(buffer) causes issues with form-data library
+  // See: https://github.com/larksuite/node-sdk/issues/121
+  const imageData = typeof image === "string" ? fs.createReadStream(image) : image;
 
   const response = await client.im.image.create({
     data: {
       image_type: imageType,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK stream type
-      image: imageStream as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK accepts Buffer or ReadStream
+      image: imageData as any,
     },
   });
 
@@ -258,16 +259,17 @@ export async function uploadFileFeishu(params: {
 
   const client = createFeishuClient(account);
 
-  // SDK expects a Readable stream, not a Buffer
-  // Use type assertion since SDK actually accepts any Readable at runtime
-  const fileStream = typeof file === "string" ? fs.createReadStream(file) : Readable.from(file);
+  // SDK accepts Buffer directly or fs.ReadStream for file paths
+  // Using Readable.from(buffer) causes issues with form-data library
+  // See: https://github.com/larksuite/node-sdk/issues/121
+  const fileData = typeof file === "string" ? fs.createReadStream(file) : file;
 
   const response = await client.im.file.create({
     data: {
       file_type: fileType,
       file_name: fileName,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK stream type
-      file: fileStream as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK accepts Buffer or ReadStream
+      file: fileData as any,
       ...(duration !== undefined && { duration }),
     },
   });
@@ -357,10 +359,13 @@ export async function sendFileFeishu(params: {
   cfg: ClawdbotConfig;
   to: string;
   fileKey: string;
+  /** Use "media" for audio/video files, "file" for documents */
+  msgType?: "file" | "media";
   replyToMessageId?: string;
   accountId?: string;
 }): Promise<SendMediaResult> {
   const { cfg, to, fileKey, replyToMessageId, accountId } = params;
+  const msgType = params.msgType ?? "file";
   const account = resolveFeishuAccount({ cfg, accountId });
   if (!account.configured) {
     throw new Error(`Feishu account "${account.accountId}" not configured`);
@@ -380,7 +385,7 @@ export async function sendFileFeishu(params: {
       path: { message_id: replyToMessageId },
       data: {
         content,
-        msg_type: "file",
+        msg_type: msgType,
       },
     });
 
@@ -399,7 +404,7 @@ export async function sendFileFeishu(params: {
     data: {
       receive_id: receiveId,
       content,
-      msg_type: "file",
+      msg_type: msgType,
     },
   });
 
@@ -522,6 +527,15 @@ export async function sendMediaFeishu(params: {
       fileType,
       accountId,
     });
-    return sendFileFeishu({ cfg, to, fileKey, replyToMessageId, accountId });
+    // Feishu requires msg_type "media" for audio/video, "file" for documents
+    const isMedia = fileType === "mp4" || fileType === "opus";
+    return sendFileFeishu({
+      cfg,
+      to,
+      fileKey,
+      msgType: isMedia ? "media" : "file",
+      replyToMessageId,
+      accountId,
+    });
   }
 }

extensions/feishu/src/reply-dispatcher.test.ts

@@ -0,0 +1,116 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const resolveFeishuAccountMock = vi.hoisted(() => vi.fn());
+const getFeishuRuntimeMock = vi.hoisted(() => vi.fn());
+const sendMessageFeishuMock = vi.hoisted(() => vi.fn());
+const sendMarkdownCardFeishuMock = vi.hoisted(() => vi.fn());
+const createFeishuClientMock = vi.hoisted(() => vi.fn());
+const resolveReceiveIdTypeMock = vi.hoisted(() => vi.fn());
+const createReplyDispatcherWithTypingMock = vi.hoisted(() => vi.fn());
+const streamingInstances = vi.hoisted(() => [] as any[]);
+
+vi.mock("./accounts.js", () => ({ resolveFeishuAccount: resolveFeishuAccountMock }));
+vi.mock("./runtime.js", () => ({ getFeishuRuntime: getFeishuRuntimeMock }));
+vi.mock("./send.js", () => ({
+  sendMessageFeishu: sendMessageFeishuMock,
+  sendMarkdownCardFeishu: sendMarkdownCardFeishuMock,
+}));
+vi.mock("./client.js", () => ({ createFeishuClient: createFeishuClientMock }));
+vi.mock("./targets.js", () => ({ resolveReceiveIdType: resolveReceiveIdTypeMock }));
+vi.mock("./streaming-card.js", () => ({
+  FeishuStreamingSession: class {
+    active = false;
+    start = vi.fn(async () => {
+      this.active = true;
+    });
+    update = vi.fn(async () => {});
+    close = vi.fn(async () => {
+      this.active = false;
+    });
+    isActive = vi.fn(() => this.active);
+
+    constructor() {
+      streamingInstances.push(this);
+    }
+  },
+}));
+
+import { createFeishuReplyDispatcher } from "./reply-dispatcher.js";
+
+describe("createFeishuReplyDispatcher streaming behavior", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    streamingInstances.length = 0;
+
+    resolveFeishuAccountMock.mockReturnValue({
+      accountId: "main",
+      appId: "app_id",
+      appSecret: "app_secret",
+      domain: "feishu",
+      config: {
+        renderMode: "auto",
+        streaming: true,
+      },
+    });
+
+    resolveReceiveIdTypeMock.mockReturnValue("chat_id");
+    createFeishuClientMock.mockReturnValue({});
+
+    createReplyDispatcherWithTypingMock.mockImplementation((opts) => ({
+      dispatcher: {},
+      replyOptions: {},
+      markDispatchIdle: vi.fn(),
+      _opts: opts,
+    }));
+
+    getFeishuRuntimeMock.mockReturnValue({
+      channel: {
+        text: {
+          resolveTextChunkLimit: vi.fn(() => 4000),
+          resolveChunkMode: vi.fn(() => "line"),
+          resolveMarkdownTableMode: vi.fn(() => "preserve"),
+          convertMarkdownTables: vi.fn((text) => text),
+          chunkTextWithMode: vi.fn((text) => [text]),
+        },
+        reply: {
+          createReplyDispatcherWithTyping: createReplyDispatcherWithTypingMock,
+          resolveHumanDelayConfig: vi.fn(() => undefined),
+        },
+      },
+    });
+  });
+
+  it("keeps auto mode plain text on non-streaming send path", async () => {
+    createFeishuReplyDispatcher({
+      cfg: {} as never,
+      agentId: "agent",
+      runtime: {} as never,
+      chatId: "oc_chat",
+    });
+
+    const options = createReplyDispatcherWithTypingMock.mock.calls[0]?.[0];
+    await options.deliver({ text: "plain text" }, { kind: "final" });
+
+    expect(streamingInstances).toHaveLength(0);
+    expect(sendMessageFeishuMock).toHaveBeenCalledTimes(1);
+    expect(sendMarkdownCardFeishuMock).not.toHaveBeenCalled();
+  });
+
+  it("uses streaming session for auto mode markdown payloads", async () => {
+    createFeishuReplyDispatcher({
+      cfg: {} as never,
+      agentId: "agent",
+      runtime: { log: vi.fn(), error: vi.fn() } as never,
+      chatId: "oc_chat",
+    });
+
+    const options = createReplyDispatcherWithTypingMock.mock.calls[0]?.[0];
+    await options.deliver({ text: "```ts\nconst x = 1\n```" }, { kind: "final" });
+
+    expect(streamingInstances).toHaveLength(1);
+    expect(streamingInstances[0].start).toHaveBeenCalledTimes(1);
+    expect(streamingInstances[0].close).toHaveBeenCalledTimes(1);
+    expect(sendMessageFeishuMock).not.toHaveBeenCalled();
+    expect(sendMarkdownCardFeishuMock).not.toHaveBeenCalled();
+  });
+});