From 14b91b0a6e2347d8f8137def768e2f76b8ae51c6 Mon Sep 17 00:00:00 2001
From: Mariano Belinky <mbelinky@gmail.com>
Date: Sun, 8 Feb 2026 09:08:55 +0100
Subject: [PATCH] Docs: document device pairing via Telegram

---
 CHANGELOG.md              |  3 +++
 docs/channels/pairing.md  | 17 +++++++++++++++++
 docs/channels/telegram.md | 11 +++++++++++
 3 files changed, 31 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e9e85a7431..0668e920aea 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,10 +7,13 @@ Docs: https://docs.openclaw.ai
 ### Added
 
 - Gateway: add `agents.create`, `agents.update`, `agents.delete` RPC methods for web UI agent management. (#11045) Thanks @advaitpaliwal.
+- Gateway: add node command allowlists (default-deny unknown node commands; configurable via `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`).
+- Plugins: add `device-pair` (Telegram `/pair` flow) and `phone-control` (iOS/Android node controls).
 
 ### Fixes
 
 - Discord: support forum/media `thread create` starter messages, wire `message thread create --message`, and harden thread-create routing. (#10062) Thanks @jarvis89757.
+- Gateway: stabilize chat routing by canonicalizing node session keys for node-originated chat methods.
 - Web UI: make chat refresh smoothly scroll to the latest messages and suppress new-messages badge flash during manual refresh.
 - Cron: route text-only isolated agent announces through the shared subagent announce flow; add exponential backoff for repeated errors; preserve future `nextRunAtMs` on restart; include current-boundary schedule matches; prevent stale threadId reuse across targets; and add per-job execution timeout. (#11641) Thanks @tyler6204.
 - Subagents: stabilize announce timing, preserve compaction metrics across retries, clamp overflow-prone long timeouts, and cap impossible context usage token totals. (#11551) Thanks @tyler6204.
diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md
index 19813155f56..bdd52975071 100644
--- a/docs/channels/pairing.md
+++ b/docs/channels/pairing.md
@@ -52,6 +52,23 @@ Treat these as sensitive (they gate access to your assistant).
 Nodes connect to the Gateway as **devices** with `role: node`. The Gateway
 creates a device pairing request that must be approved.
 
+### Pair via Telegram (recommended for iOS)
+
+If you use the `device-pair` plugin, you can do first-time device pairing entirely from Telegram:
+
+1. In Telegram, message your bot: `/pair`
+2. The bot replies with two messages: an instruction message and a separate **setup code** message (easy to copy/paste in Telegram).
+3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
+4. Paste the setup code and connect.
+5. Back in Telegram: `/pair approve`
+
+The setup code is a base64-encoded JSON payload that contains:
+
+- `url`: the Gateway WebSocket URL (`ws://...` or `wss://...`)
+- `token`: a short-lived pairing token
+
+Treat the setup code like a password while it is valid.
+
 ### Approve a node device
 
 ```bash
diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md
index f4d7971c602..31a61fc042e 100644
--- a/docs/channels/telegram.md
+++ b/docs/channels/telegram.md
@@ -157,10 +157,21 @@ More help: [Channel troubleshooting](/channels/troubleshooting).
 Notes:
 
 - Custom commands are **menu entries only**; OpenClaw does not implement them unless you handle them elsewhere.
+- Some commands can be handled by plugins/skills without being registered in Telegram’s command menu. These still work when typed (they just won't show up in `/commands` / the menu).
 - Command names are normalized (leading `/` stripped, lowercased) and must match `a-z`, `0-9`, `_` (1–32 chars).
 - Custom commands **cannot override native commands**. Conflicts are ignored and logged.
 - If `commands.native` is disabled, only custom commands are registered (or cleared if none).
 
+### Device pairing commands (`device-pair` plugin)
+
+If the `device-pair` plugin is installed, it adds a Telegram-first flow for pairing a new phone:
+
+1. `/pair` generates a setup code (sent as a separate message for easy copy/paste).
+2. Paste the setup code in the iOS app to connect.
+3. `/pair approve` approves the latest pending device request.
+
+More details: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios).
+
 ## Limits
 
 - Outbound text is chunked to `channels.telegram.textChunkLimit` (default 4000).