diff --git a/docs/im/feishu.md b/docs/im/feishu.md
index 1f5fc643..cb447b92 100644
--- a/docs/im/feishu.md
+++ b/docs/im/feishu.md
@@ -1,6 +1,6 @@
 # 飞书接入
 
-> 飞书 Adapter 的实际接入说明，基于当前仓库代码。
+> 飞书 Adapter 的接入教程。官方已经提供了**预配好权限的模板机器人**，跟着下面几步点一点就能完成接入。
 
 ## 适用场景
 
@@ -8,127 +8,91 @@
 
 实现入口：`adapters/feishu/index.ts`
 
-## 启动前准备
+## 1. 一键创建飞书机器人
 
-### 1. 创建飞书应用
+直接打开下面的链接创建机器人——这是官方为 OpenClaw 提前配好所有权限（消息、事件、卡片回调等）的模板，省去手动配 scope 和事件订阅：
 
-在飞书开放平台创建企业自建应用，拿到：
+👉 [立即创建飞书机器人](https://open.feishu.cn/page/openclaw?form=multiAgent)
 
-- `App ID`
-- `App Secret`
+![一键创建入口](../images/im/feishu/01-create-app-entry.png)
 
-### 2. 配权限
+随便给你自己的机器人取一个名字，点击创建：
 
-至少确认这些能力可用：
+![取名并创建](../images/im/feishu/02-name-bot.png)
 
-- `im:message`
-- `im:message:send_as_bot`
-- `im:resource`
+创建成功后，把 **App ID** 和 **App Secret** 保存下来，接着去配置机器人菜单。
 
-### 3. 配事件订阅
+## 2. 配置自定义菜单（/projects /new /clear）
 
-当前实现使用飞书 WebSocket 长连接接事件，不需要公网回调地址。
+进入[飞书开发者后台](https://open.feishu.cn/app?lang=zh-CN)，选择刚创建的机器人，进入机器人配置页：
 
-需要注册的事件：
+![开发者后台](../images/im/feishu/03-dev-console.png)
 
-- `im.message.receive_v1`
-- `card.action.trigger`
+进入「机器人菜单」开始配置：
 
-### 4. 发布应用
+![进入菜单配置](../images/im/feishu/04-menu-enter.png)
 
-应用至少需要处于可用发布状态，否则 bot 无法正常收发消息。
+依次添加 3 个命令：
 
-## 在 Desktop Webapp 里配置
+**/projects** — 切换最近使用的项目
 
-打开 `Settings -> IM 接入 -> 飞书`，填写：
+![菜单 /projects](../images/im/feishu/05-menu-projects.png)
 
-- `App ID`
-- `App Secret`
-- `Encrypt Key`，按你的事件配置填写
-- `Verification Token`，按你的事件配置填写
-- `Allowed Users`，可选
-- `Streaming Card`
+**/new** — 开启新对话
 
-配置结构示例：
+![菜单 /new](../images/im/feishu/06-menu-new.png)
 
-```json
-{
-  "serverUrl": "ws://127.0.0.1:3456",
-  "defaultProjectDir": "/Users/me/workspace/my-project",
-  "feishu": {
-    "appId": "cli_xxx",
-    "appSecret": "xxx",
-    "encryptKey": "",
-    "verificationToken": "",
-    "allowedUsers": ["ou_xxx"],
-    "streamingCard": false
-  }
-}
-```
+**/clear** — 清空上下文
 
-环境变量也可覆盖配置文件：
+![菜单 /clear](../images/im/feishu/07-menu-clear.png)
 
-```bash
-export FEISHU_APP_ID="cli_xxx"
-export FEISHU_APP_SECRET="xxx"
-export FEISHU_ENCRYPT_KEY=""
-export FEISHU_VERIFICATION_TOKEN=""
-export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
-```
+三个都配好后点击保存：
 
-## 启动
+![保存菜单](../images/im/feishu/08-menu-save.png)
 
-```bash
-cd adapters
-bun install
-bun run feishu
-```
+最后点击「创建新版本并发布」让菜单生效：
 
-## 首次配对
+![创建版本并发布](../images/im/feishu/09-publish-version.png)
 
-飞书侧的配对和 Telegram 一样，都是走 Webapp 生成的全局配对码。
+**命令作用说明：**
 
-流程：
+- `/projects`：列出最近使用的项目，支持切换当前会话绑定的目录
+- `/new`：开启新对话
+- `/clear`：清空当前会话上下文
 
-1. 在 Desktop Webapp 里生成 6 位配对码
-2. 飞书私聊 bot
-3. 直接发送配对码
-4. `adapters/common/pairing.ts` 验证成功后，把当前 `open_id` 写进 `feishu.pairedUsers`
+## 3. 在 Claude Code Haha 桌面端填写
 
-注意：
+### 3.1 填写 App ID / App Secret
 
-- 当前实现把飞书用户标识存成 `open_id`
-- `allowedUsers` 也是按 `open_id` 比较
-- 码一次性使用，60 分钟过期
+打开桌面端 `设置 → IM 接入 → 飞书`，把前面拿到的两把钥匙填进去：
 
-## 日常使用流程
+![填写 App ID / App Secret](../images/im/feishu/10-fill-app-credentials.png)
 
-### 首次消息
+### 3.2 生成配对码
 
-`adapters/feishu/index.ts` 处理逻辑：
+点击「生成配对码」按钮，得到 6 位码：
 
-1. 通过长连接收到 `im.message.receive_v1`
-2. 提取文本内容
-3. 只接受 `p2p`
-4. 校验授权
-5. 没有 session 时：
-   - 先尝试恢复 `adapter-sessions.json`
-   - 否则按 `defaultProjectDir` 建 session
-   - 如果没默认项目，则列最近项目让用户回复编号
+![生成配对码](../images/im/feishu/11-generate-pairing-code.png)
 
-### 项目选择
+![配对码详情](../images/im/feishu/12-pairing-code-detail.png)
 
-没有默认项目时，adapter 会调用 `GET /api/sessions/recent-projects`，然后在飞书里发编号列表。
+**记得点保存！！**
 
-用户回复编号后：
+## 4. 飞书机器人与桌面端配对
 
-- adapter 调 `POST /api/sessions`
-- 建立 `/ws/:sessionId` 连接
-- 把映射写入 `~/.claude/adapter-sessions.json`
+随便给刚才创建的机器人发送一条消息，按提示把上一步的 6 位配对码发给它：
+
+![在飞书里发配对码](../images/im/feishu/13-send-code-in-feishu.png)
+
+看到配对成功提示后，就可以用飞书在手机上远程驱动桌面端 Claude Code Haha 了：
+
+![配对成功](../images/im/feishu/14-pair-success.png)
+
+![可以开始对话](../images/im/feishu/15-pair-done.png)
 
 ## 支持的命令
 
-飞书当前支持文本命令和中文别名：
+除菜单按钮外，飞书 adapter 还支持文本命令和中文别名：
 
 - `/help` 或 `帮助`
 - `/status` 或 `状态`
@@ -139,57 +103,59 @@ bun run feishu
 
 ## 权限审批
 
-飞书使用交互卡片，而不是 Telegram 的 inline button。
-
-当 Claude 请求权限时：
-
-1. adapter 构造 interactive card
-2. 用户点击允许/拒绝
-3. 飞书回调 `card.action.trigger`
-4. adapter 调用 `bridge.sendPermissionResponse(...)`
+当 Claude 请求敏感权限时，adapter 会在飞书里发送交互卡片，点击「允许 / 拒绝」即可把结果回传给桌面端。
 
 ## 返回消息的表现
 
-飞书侧也支持流式更新，但渲染方式和 Telegram 不同：
-
 - 普通文本通过 `post` 消息发送
 - 权限审批通过卡片发送
 - 流式内容优先 patch 同一条消息
 - 完成后按 30000 字左右分片
 
-`streamingCard` 字段当前已经进入配置模型，但 `adapters/feishu/index.ts` 里实际消息渲染仍以文本 patch / card 为主，文档里不应把它写成一个已经成型的独立体验开关。
+## 启动 adapter
+
+桌面端会自动把 adapter 作为 sidecar 拉起。如果你在本地开发，需要手动启动：
+
+```bash
+cd adapters
+bun install
+bun run feishu
+```
+
+## 环境变量覆盖（可选）
+
+```bash
+export FEISHU_APP_ID="cli_xxx"
+export FEISHU_APP_SECRET="xxx"
+export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
+```
 
 ## 常见问题
 
+### 一键创建后的机器人权限够用吗？
+
+OpenClaw 官方模板已预配 `im:message`、`im:message:send_as_bot`、`im:resource`、`im.message.receive_v1`、`card.action.trigger` 等所有所需权限，**不需要再手动去配 scope 或事件订阅**。
+
 ### 收不到消息
 
 优先检查：
 
-- App ID / App Secret 是否正确
-- 应用是否已发布
-- 是否启用了 `im.message.receive_v1`
-- 是否启用了 `card.action.trigger`
+- 机器人是否已发布（菜单改完需要「创建新版本并发布」）
 - 是否真的是和 bot 的私聊，而不是群聊
 
 ### 权限按钮点了没反应
 
-通常是 `card.action.trigger` 没配置好，或者事件订阅鉴权配置和本地 `encryptKey` / `verificationToken` 不匹配。
+通常是 `card.action.trigger` 没生效，重新在开发者后台发布一次版本即可。
 
 ### 一直提示未授权
 
-优先检查：
-
-- 配对码是否还在有效期
-- 发送的是不是当前有效码
-- `allowedUsers` 填的是不是 `open_id`
-- `feishu.pairedUsers` 里是否已写入当前用户
+- 配对码是否仍在 60 分钟有效期内
+- 发的是不是桌面端当前这一枚（重新生成后旧的立即失效）
+- `feishu.pairedUsers` 里是否已经写入当前 `open_id`
 
 ### 会话没恢复
 
-检查：
-
-- `~/.claude/adapter-sessions.json` 是否成功写入
-- Desktop server 里的 session 是否仍存在
+检查 `~/.claude/adapter-sessions.json` 是否能正常写入，以及 Desktop server 里的 session 是否仍存在。
 
 ## 源码入口
 
diff --git a/docs/im/telegram.md b/docs/im/telegram.md
index 8b19c8ce..ca55a0fe 100644
--- a/docs/im/telegram.md
+++ b/docs/im/telegram.md
@@ -1,6 +1,6 @@
 # Telegram 接入
 
-> Telegram Adapter 的实际接入说明，基于当前仓库代码，而不是旧 README。
+> Telegram Adapter 的接入教程。找 BotFather 拿 Token，桌面端填完配对即可。
 
 ## 适用场景
 
@@ -8,135 +8,62 @@ Telegram 方案适合个人私聊远程使用。当前实现只处理 `private c
 
 实现入口：`adapters/telegram/index.ts`
 
-## 启动前准备
+## 1. 创建 Telegram 机器人
 
-### 1. 创建 Bot
+在 Telegram 里搜索官方账号 **@BotFather**：
 
-在 Telegram 里找 `@BotFather`：
+![搜索 BotFather](../images/im/telegram/01-search-botfather.png)
 
-1. 发送 `/newbot`
-2. 按提示创建 bot
-3. 拿到 `Bot Token`
+给它发送 `/newbot`：
 
-### 2. 在 Desktop Webapp 里填写配置
+![发送 /newbot](../images/im/telegram/02-newbot-command.png)
 
-打开 `Settings -> IM 接入 -> Telegram`，填写：
+按提示走完三步：
 
-- `Bot Token`
-- `Allowed Users`，可选
-- 全局 `Default Project`
+- **取一个机器人名称**，例如 `ClaudeCodeHaha机器人`
+- **取一个机器人用户名**，要求全英文字母，且必须以 `_bot` 结尾，例如 `jiang_cc_hah_bot`
+- 创建成功后，复制 BotFather 返回的 **Bot Token**
 
-也可以直接写 `~/.claude/adapters.json`，但当前推荐从 Webapp 配。
+![复制 Bot Token](../images/im/telegram/03-bot-token.png)
 
-配置结构示例：
+## 2. 在 Claude Code Haha 桌面端填写
 
-```json
-{
-  "serverUrl": "ws://127.0.0.1:3456",
-  "defaultProjectDir": "/Users/me/workspace/my-project",
-  "telegram": {
-    "botToken": "123456:ABC-DEF...",
-    "allowedUsers": [123456789]
-  }
-}
-```
+### 2.1 填写 Bot Token
 
-环境变量优先级更高：
+打开桌面端 `设置 → IM 接入 → Telegram`，把上一步的 Bot Token 填进去：
 
-```bash
-export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
-export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
-```
+![填写 Bot Token](../images/im/telegram/04-fill-bot-token.png)
 
-## 启动
+### 2.2 生成配对码
 
-```bash
-cd adapters
-bun install
-bun run telegram
-```
+点击「生成配对码」按钮，拿到 6 位配对码后点击保存：
 
-## 首次配对
+![生成配对码](../images/im/telegram/05-generate-pairing-code.png)
 
-Telegram 侧的授权入口不再只依赖 `allowedUsers`。
+## 3. 机器人与桌面端配对
 
-当前真实逻辑：
+随便给刚才创建的机器人发送一条消息，按提示输入配对码。看到下面的配对成功提示，就可以从手机 Telegram 远程驱动桌面端 Claude Code Haha 了：
 
-1. 在 Desktop Webapp 里生成配对码
-2. 去 Telegram 私聊 bot
-3. 把那 6 位码直接发给 bot
-4. adapter 调用 `tryPair(...)`
-5. 配对成功后，把当前 Telegram user 写进 `telegram.pairedUsers`
-
-特点：
-
-- 配对码 60 分钟过期
-- 配对成功后立即失效
-- 和飞书共用同一枚全局配对码
-- 连续输错有速率限制
-
-## 日常使用流程
-
-### 首次消息
-
-`adapters/telegram/index.ts` 的流程是：
-
-1. 校验是否私聊
-2. 去重
-3. 校验是否已授权
-4. 没有 session 时：
-   - 优先恢复 `adapter-sessions.json` 里的旧 session
-   - 否则用 `defaultProjectDir` 创建新 session
-   - 如果没配默认项目，则拉最近项目列表让你选
-
-### 项目选择
-
-当没有默认项目时，bot 会调用 `GET /api/sessions/recent-projects`，返回最近项目列表，并要求你回复编号。
-
-选中后：
-
-- adapter 用 `POST /api/sessions` 创建 session
-- 把 `chatId -> sessionId -> workDir` 写进 `~/.claude/adapter-sessions.json`
-- 后续消息继续复用
+![配对成功](../images/im/telegram/06-pair-success.png)
 
 ## 支持的命令
 
-### `/start`
-
-显示帮助和可用命令。
-
-### `/projects`
-
-切换项目，重新显示最近项目列表。
-
-### `/status`
-
-查看当前会话的项目、模型、运行状态和任务摘要。
-
-### `/clear`
-
-清空当前会话上下文，保留当前项目绑定。
-
-### `/new`
-
-清空当前 chat 绑定的 session，并重新选择项目。
-
-### `/help`
-
-显示当前可用命令。
-
-### `/stop`
-
-向当前 session 发送 `stop_generation`。
+- `/start` — 显示帮助和可用命令
+- `/projects` — 切换项目，重新显示最近项目列表
+- `/status` — 查看当前会话的项目、模型、运行状态和任务摘要
+- `/clear` — 清空当前会话上下文，保留项目绑定
+- `/new` — 清空当前 chat 绑定的 session，并重新选择项目
+- `/help` — 显示当前可用命令
+- `/stop` — 向当前 session 发送 `stop_generation`
 
 ## 权限审批
 
-当 Claude 需要敏感权限时，Telegram adapter 会发带按钮的消息：
+当 Claude 请求敏感权限时，Telegram adapter 会发带按钮的消息：
 
 - `✅ 允许`
 - `❌ 拒绝`
 
-点击后，adapter 会把结果通过 `permission_response` 发回 Desktop server。
+点击后 adapter 会把结果通过 `permission_response` 回传给 Desktop server。
 
 ## 返回消息的表现
 
@@ -152,6 +79,23 @@ Telegram 侧有一层流式缓冲：
 - `adapters/common/format.ts`
 - `adapters/common/ws-bridge.ts`
 
+## 启动 adapter
+
+桌面端会自动把 adapter 作为 sidecar 拉起。如果你在本地开发，需要手动启动：
+
+```bash
+cd adapters
+bun install
+bun run telegram
+```
+
+## 环境变量覆盖（可选）
+
+```bash
+export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
+export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
+```
+
 ## 常见问题
 
 ### bot 启动时报缺少 token
@@ -160,16 +104,14 @@ Telegram 侧有一层流式缓冲：
 
 ### 能打开设置页但 bot 不工作
 
-Webapp 只负责配置，不会自动拉起 `bun run telegram`。
+Webapp 只负责配置，不会自动拉起 `bun run telegram`（桌面端发布版会通过 sidecar 自动拉起）。
 
 ### 发消息提示未授权
 
-优先检查：
-
-- 是否已经在 Webapp 里生成配对码
-- 配对码是否过期
+- 是否已经在桌面端生成配对码
+- 配对码是否在 60 分钟有效期内
 - 是否把码发到了正确的 bot 私聊
-- `allowedUsers` / `pairedUsers` 是否真的包含当前账号
+- 连续输错会有速率限制，等几分钟再试
 
 ### 每次重启后会话丢失
 
diff --git a/docs/images/im/feishu/01-create-app-entry.png b/docs/images/im/feishu/01-create-app-entry.png
new file mode 100644
index 00000000..256bc128
Binary files /dev/null and b/docs/images/im/feishu/01-create-app-entry.png differ
diff --git a/docs/images/im/feishu/02-name-bot.png b/docs/images/im/feishu/02-name-bot.png
new file mode 100644
index 00000000..ddb774af
Binary files /dev/null and b/docs/images/im/feishu/02-name-bot.png differ
diff --git a/docs/images/im/feishu/03-dev-console.png b/docs/images/im/feishu/03-dev-console.png
new file mode 100644
index 00000000..8e08efa1
Binary files /dev/null and b/docs/images/im/feishu/03-dev-console.png differ
diff --git a/docs/images/im/feishu/04-menu-enter.png b/docs/images/im/feishu/04-menu-enter.png
new file mode 100644
index 00000000..ec8659b5
Binary files /dev/null and b/docs/images/im/feishu/04-menu-enter.png differ
diff --git a/docs/images/im/feishu/05-menu-projects.png b/docs/images/im/feishu/05-menu-projects.png
new file mode 100644
index 00000000..8e211c3a
Binary files /dev/null and b/docs/images/im/feishu/05-menu-projects.png differ
diff --git a/docs/images/im/feishu/06-menu-new.png b/docs/images/im/feishu/06-menu-new.png
new file mode 100644
index 00000000..2302fab7
Binary files /dev/null and b/docs/images/im/feishu/06-menu-new.png differ
diff --git a/docs/images/im/feishu/07-menu-clear.png b/docs/images/im/feishu/07-menu-clear.png
new file mode 100644
index 00000000..3e24c630
Binary files /dev/null and b/docs/images/im/feishu/07-menu-clear.png differ
diff --git a/docs/images/im/feishu/08-menu-save.png b/docs/images/im/feishu/08-menu-save.png
new file mode 100644
index 00000000..268dde60
Binary files /dev/null and b/docs/images/im/feishu/08-menu-save.png differ
diff --git a/docs/images/im/feishu/09-publish-version.png b/docs/images/im/feishu/09-publish-version.png
new file mode 100644
index 00000000..93b713d2
Binary files /dev/null and b/docs/images/im/feishu/09-publish-version.png differ
diff --git a/docs/images/im/feishu/10-fill-app-credentials.png b/docs/images/im/feishu/10-fill-app-credentials.png
new file mode 100644
index 00000000..6ea32a71
Binary files /dev/null and b/docs/images/im/feishu/10-fill-app-credentials.png differ
diff --git a/docs/images/im/feishu/11-generate-pairing-code.png b/docs/images/im/feishu/11-generate-pairing-code.png
new file mode 100644
index 00000000..797b5e5e
Binary files /dev/null and b/docs/images/im/feishu/11-generate-pairing-code.png differ
diff --git a/docs/images/im/feishu/12-pairing-code-detail.png b/docs/images/im/feishu/12-pairing-code-detail.png
new file mode 100644
index 00000000..a2d0a57f
Binary files /dev/null and b/docs/images/im/feishu/12-pairing-code-detail.png differ
diff --git a/docs/images/im/feishu/13-send-code-in-feishu.png b/docs/images/im/feishu/13-send-code-in-feishu.png
new file mode 100644
index 00000000..b0be0433
Binary files /dev/null and b/docs/images/im/feishu/13-send-code-in-feishu.png differ
diff --git a/docs/images/im/feishu/14-pair-success.png b/docs/images/im/feishu/14-pair-success.png
new file mode 100644
index 00000000..16fd813f
Binary files /dev/null and b/docs/images/im/feishu/14-pair-success.png differ
diff --git a/docs/images/im/feishu/15-pair-done.png b/docs/images/im/feishu/15-pair-done.png
new file mode 100644
index 00000000..d3e39705
Binary files /dev/null and b/docs/images/im/feishu/15-pair-done.png differ
diff --git a/docs/images/im/telegram/01-search-botfather.png b/docs/images/im/telegram/01-search-botfather.png
new file mode 100644
index 00000000..aa333633
Binary files /dev/null and b/docs/images/im/telegram/01-search-botfather.png differ
diff --git a/docs/images/im/telegram/02-newbot-command.png b/docs/images/im/telegram/02-newbot-command.png
new file mode 100644
index 00000000..02c5ea7e
Binary files /dev/null and b/docs/images/im/telegram/02-newbot-command.png differ
diff --git a/docs/images/im/telegram/03-bot-token.png b/docs/images/im/telegram/03-bot-token.png
new file mode 100644
index 00000000..c07e983f
Binary files /dev/null and b/docs/images/im/telegram/03-bot-token.png differ
diff --git a/docs/images/im/telegram/04-fill-bot-token.png b/docs/images/im/telegram/04-fill-bot-token.png
new file mode 100644
index 00000000..b0f60196
Binary files /dev/null and b/docs/images/im/telegram/04-fill-bot-token.png differ
diff --git a/docs/images/im/telegram/05-generate-pairing-code.png b/docs/images/im/telegram/05-generate-pairing-code.png
new file mode 100644
index 00000000..07195bdc
Binary files /dev/null and b/docs/images/im/telegram/05-generate-pairing-code.png differ
diff --git a/docs/images/im/telegram/06-pair-success.png b/docs/images/im/telegram/06-pair-success.png
new file mode 100644
index 00000000..7de19e66
Binary files /dev/null and b/docs/images/im/telegram/06-pair-success.png differ