From 6e82fe8a2e988ccb0fd6467e69bd313543b663f8 Mon Sep 17 00:00:00 2001
From: Alex's Mac <alexmac@AlexsdeMac-mini-2.local>
Date: Sun, 29 Mar 2026 08:49:01 +0800
Subject: [PATCH] docs: fix platform setup guides, add multi-agent capabilities
 (#31, #33, #34)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address user-reported issues and integrate new platform capabilities:

Discord (Issue #34 — routing bug):
- Add Step 5b: channel permission isolation to prevent agent
  conversation mixing (single-bot and multi-bot approaches)
- Update multi-account support status (available in current versions)

Feishu (Issue #31 — multi-agent support):
- Document groupSessionScope: "group_topic" for per-topic session
  isolation (OpenClaw >= 2026.3.1), shown as incremental config patch
- Add CLI alternative: openclaw config set
- Add SecretRef bug caveat (openclaw #47436) in multi-app section
- Fix issue citation: #10242 (DM threads) → #29791 (group chat topics)

Getting Started (Issue #33 — beginner experience):
- Fix deployment order with clear "Manual" vs "Agent-automated" labels
- Note that steps 5-9 can be fully automated via DEPLOY.md
- Add prerequisites checklist covering all platforms
- Add common mistakes section (5 items)

Known Issues:
- Add Feishu P1 (resolved) entry with groupSessionScope resolution
- Fix typographic quotes in YAML examples (would cause parse failures)

All changes in both Chinese and English versions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/DISCORD_SETUP.md      | 42 +++++++++++++++++++-
 docs/FEISHU_SETUP.md       | 29 +++++++++++++-
 docs/GETTING_STARTED.md    | 78 +++++++++++++++++++++++++++++++++++---
 docs/KNOWN_ISSUES.md       | 36 ++++++++++++++----
 docs/en/DISCORD_SETUP.md   | 42 +++++++++++++++++++-
 docs/en/FEISHU_SETUP.md    | 29 +++++++++++++-
 docs/en/GETTING_STARTED.md | 78 +++++++++++++++++++++++++++++++++++---
 docs/en/KNOWN_ISSUES.md    | 22 +++++++++++
 8 files changed, 335 insertions(+), 21 deletions(-)

diff --git a/docs/DISCORD_SETUP.md b/docs/DISCORD_SETUP.md
index 004c59a..45645e8 100644
--- a/docs/DISCORD_SETUP.md
+++ b/docs/DISCORD_SETUP.md
@@ -129,6 +129,46 @@ Bot 在 Discord 中显示为"在线"即连接成功。
 
 ---
 
+## Step 5b：配置频道权限隔离（重要！）
+
+> **Warning**：如果不做权限隔离，单个 bot 服务多个 Agent 时可能会在错误的频道发送消息，导致不同 Agent（如 CoS 和 Ops）的对话混在一起。此问题已在 [Issue #34](https://github.com/AlexAnys/opencrew/issues/34) 中报告。以下步骤可以避免此问题。
+
+核心思路：bot 只能在**明确分配给它的频道**中发送消息。在服务器级别拒绝发送消息权限，然后在每个频道中单独允许。
+
+### 单 Bot 配置（默认方案）
+
+1. **创建 bot 角色**（如"OpenCrew Bot"）：
+   - 服务器设置 → 身份组 → 创建身份组
+   - **不要授予管理员权限** -- 管理员权限会绕过所有频道权限覆盖
+   - 授予以下服务器级权限：`查看频道`、`读取消息历史`、`添加反应`、`创建公开帖子`、`创建私密帖子`、`在帖子中发送消息`、`管理帖子`
+   - **不要授予**服务器级别的 `发送消息` 权限
+
+2. **将角色分配给 bot**：
+   - 服务器设置 → 成员 → 找到 bot → 添加"OpenCrew Bot"角色
+
+3. **为每个 Agent 频道添加权限覆盖**（`#hq`、`#cto`、`#build` 等）：
+   - 点击频道名 → 编辑频道 → 权限
+   - 点击"+"添加"OpenCrew Bot"角色
+   - 将 `发送消息` 设为 **允许**（绿色勾号）
+
+4. **验证**：bot 现在应该只能在你明确允许的频道中发送消息。可以测试 bot 是否无法在 Agent 频道之外的随机频道中发言。
+
+### 多 Bot 配置
+
+如果你为每个 Agent 运行独立的 bot，请为每个 bot 创建**单独的角色**：
+
+1. 创建角色："CoS Bot"、"CTO Bot"、"Builder Bot" 等
+2. 每个角色：在服务器级别拒绝 `发送消息`（同上）
+3. 每个角色：仅在指定频道允许 `发送消息`
+   - "CoS Bot" 角色 → 仅在 `#hq` 允许发送消息
+   - "CTO Bot" 角色 → 仅在 `#cto` 允许发送消息
+   - "Builder Bot" 角色 → 仅在 `#build` 允许发送消息
+4. 为每个 bot 分配对应的角色
+
+> **注意**：这就是 Issue #34 中提到的方案——频道不是"公开"让任何 bot 随意发送的，而是手动限制每个 bot 只能在其指定频道发送消息。
+
+---
+
 ## Step 6：获取 Channel ID（两种方法）
 
 ### 方法 A（推荐）：开启开发者模式复制
@@ -167,7 +207,7 @@ openclaw channels resolve --channel discord "#hq" --json
 注意事项：
 - 每个 Bot 需要单独邀请到服务器
 - 超过 75 个服务器的 Bot 需要单独申请 Message Content Intent 审批
-- OpenClaw 多账户支持仍在开发中，参考 [PR #3672](https://github.com/open-claw/open-claw/pull/3672)
+- OpenClaw 多账户支持已在当前版本中可用。参见 [Issue #3306](https://github.com/openclaw/openclaw/issues/3306) 了解社区验证情况
 
 > **提示**：Discord 服务器最多 50 个 Bot，OpenCrew 的 7 个 Agent 远低于此限制。对于大多数用户，单 Bot + 频道路由已经足够。
 
diff --git a/docs/FEISHU_SETUP.md b/docs/FEISHU_SETUP.md
index cbfac02..efbaf09 100644
--- a/docs/FEISHU_SETUP.md
+++ b/docs/FEISHU_SETUP.md
@@ -20,7 +20,33 @@ OpenCrew 在 Slack 上的核心模型是"频道=岗位，Thread=任务"——每
 - **"话题=任务"暂不可用** — 同一个群组内的所有对话是平铺的，不能按 thread 隔离不同任务
 - 实际影响：当一个 Agent 同时处理多个任务时，对话会混在一起。对于轻量使用（一次一个任务）影响不大；高频并行任务场景下体验会打折扣
 
-> 这是 OpenClaw 飞书插件的已知限制（[Issue #10242](https://github.com/openclaw/openclaw/issues/10242)），不是飞书平台本身的限制。后续插件更新可能会解决。
+> 这是 OpenClaw 飞书插件的已知限制（[Issue #29791](https://github.com/openclaw/openclaw/issues/29791)），不是飞书平台本身的限制。
+
+### 更新：`groupSessionScope`（OpenClaw >= 2026.3.1）
+
+从 OpenClaw 2026.3.1 开始，内置飞书插件支持 `groupSessionScope: "group_topic"`，可以实现按话题隔离会话——等同于 Slack 的 thread 隔离行为。
+
+启用方式：在你现有的飞书频道配置中添加 `groupSessionScope`（不要覆盖其他设置）：
+
+```yaml
+channels:
+  feishu:
+    # ... 你现有的 appId、appSecret 等配置 ...
+    groupSessionScope: "group_topic"    # 添加这一行
+```
+
+或通过命令行：
+
+```bash
+openclaw config set channels.feishu.groupSessionScope group_topic
+```
+
+启用后：
+- 群组内的每个飞书话题拥有独立的会话隔离
+- 并发任务不再互相干扰
+- 行为与 Slack 的"thread = 任务"模型一致
+
+> **注意**：`groupSessionScope` 需要使用 **OpenClaw 内置飞书插件**。社区插件（[AlexAnys/feishu-openclaw](https://github.com/AlexAnys/feishu-openclaw)）不支持此参数——你必须使用 OpenClaw >= 2026.3.1 自带的内置插件。
 
 ---
 
@@ -261,6 +287,7 @@ agents:
 - 每个应用需独立配置事件订阅（`im.message.receive_v1`）和权限（参考 [Step 2](#step-2配置权限--事件订阅)）
 - "一群一 Agent"模式下，每个群只添加对应的 bot，避免消息重复
 - A2A 通信不受影响 — 走 OpenClaw 内部 `sessions_send`，与 bot 数量无关
+- **已知 Bug**：多账户模式下使用 `SecretRef`（如通过 Kubernetes Secret 或外部密钥管理器存储 `appSecret`）时，网关重启后凭证可能无法正确解析（[OpenClaw Issue #47436](https://github.com/openclaw/openclaw/issues/47436)）。临时方案：在配置文件中使用明文密钥（注意设置文件权限），或在修改凭证后重启两次网关
 
 ---
 
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
index 531f4a2..cbc676a 100644
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -8,16 +8,48 @@
 
 ---
 
-## 前置条件
+## 前置条件清单
 
-在开始前，请确认：
+在开始前，逐项确认：
 
-- **OpenClaw 已安装并可用**：运行 `openclaw status` 能看到正常输出
-- **Slack workspace 已创建**：你有管理员权限
-- **基本命令行能力**：能在终端里复制粘贴命令执行（或者让你现有的 OpenClaw 代为执行）
+- [ ] **OpenClaw 已安装并可用**：运行 `openclaw status` 能看到正常输出
+- [ ] **消息平台已就绪**：Slack workspace、Discord 服务器或飞书组织——且你有管理员权限
+- [ ] **基本命令行能力**：能在终端里复制粘贴命令执行（或者让你现有的 OpenClaw 代为执行）
+- [ ] **已在平台上创建 Bot/App**：必须先创建 bot/app，然后再接入 OpenClaw（详见下方平台指南）
 
 > 不确定 OpenClaw 怎么装？参考 [OpenClaw 官方文档](https://docs.openclaw.ai/)
 
+### 正确的部署顺序
+
+按以下顺序操作。最常见的错误是在消息平台上的 bot 还没配好之前就尝试配置 OpenClaw 绑定。
+
+```
+人工操作（你在平台上完成）：
+  1. 在消息平台上创建 bot/app（Discord/Slack/飞书）
+  2. 在平台上配置权限和 intents/scopes
+  3. 邀请 bot 到你的服务器/workspace/群组
+  4. 创建 Agent 频道/群组
+
+Agent 自动化（你的 OpenClaw agent 执行——参见 DEPLOY.md）：
+  5. 把平台接入 OpenClaw（openclaw channels add）
+  6. 部署 OpenCrew 文件（shared 协议 + workspace）
+  7. 写入 OpenClaw 配置（Agent 绑定、Channel ID）
+  8. 重启 gateway（openclaw gateway restart）
+  9. 验证（发测试消息）
+```
+
+> 步骤 5-9 可以通过向你现有的 OpenClaw agent 发送 [DEPLOY.md](../DEPLOY.md) 中的部署提示来全自动完成。
+
+### 平台接入指南
+
+| 平台 | 接入指南 | 预计时间 |
+|------|---------|---------|
+| Slack | [SLACK_SETUP.md](SLACK_SETUP.md) | 约 15 分钟 |
+| Discord | [DISCORD_SETUP.md](DISCORD_SETUP.md) | 约 15 分钟 |
+| 飞书 | [FEISHU_SETUP.md](FEISHU_SETUP.md) | 约 20 分钟 |
+
+> **提示**：先完成对应平台的接入指南（上述步骤 1-4），然后回到本文档继续 Phase 2。
+
 ---
 
 ## Phase 1：Slack 准备（约 20 分钟）
@@ -245,6 +277,42 @@ sudo chown -R $USER ~/.openclaw/
 
 ---
 
+## 新手常见错误
+
+以下是新用户最常遇到的问题：
+
+### 1. 部署顺序搞反
+
+**错误**：在消息平台上还没创建 bot 就尝试运行 `openclaw channels add` 或配置绑定。
+
+**解决**：务必先在消息平台上创建并配置好 bot/app。参见上方[正确的部署顺序](#正确的部署顺序)。
+
+### 2. 跳过频道权限隔离（Discord）
+
+**错误**：使用单 bot 但保留默认权限，bot 可以在任何频道发消息。这会导致不同 Agent 的对话混在一起（Issue #34）。
+
+**解决**：按照 Discord 接入指南中的[频道权限隔离](DISCORD_SETUP.md#step-5b配置频道权限隔离重要)步骤操作。
+
+### 3. 忘记重启 gateway
+
+**错误**：修改了配置或绑定但没有重启。配置不会自动生效。
+
+**解决**：修改配置后务必运行 `openclaw gateway restart`，然后用 `openclaw status` 验证。
+
+### 4. Channel ID 填错
+
+**错误**：复制了错误的 Channel ID 或搞混了不同频道的 ID。
+
+**解决**：逐个核对配置中的 Channel ID 与消息平台中的实际 ID。可以用 `openclaw channels resolve` 验证。
+
+### 5. Bot 没被邀请到频道
+
+**错误**：创建了频道但忘了邀请 bot（Slack）或添加 bot 角色（Discord）。
+
+**解决**：Slack 中在每个频道执行 `/invite @bot名`。Discord 中确保 bot 角色有"查看频道"权限。飞书中通过群设置添加机器人。
+
+---
+
 ## 常用命令速查
 
 ```bash
diff --git a/docs/KNOWN_ISSUES.md b/docs/KNOWN_ISSUES.md
index b0c7563..5da0cd8 100644
--- a/docs/KNOWN_ISSUES.md
+++ b/docs/KNOWN_ISSUES.md
@@ -21,11 +21,11 @@
 - `replyToMode: "all"` 可以确保回复进 thread
 - `channels.slack.thread.historyScope = "thread"` + `inheritParent=false` 可以确保 thread 内历史隔离
 
-但它们**无法把“每条新的 root message”自动变成一个新 session**。
+但它们**无法把"每条新的 root message"自动变成一个新 session**。
 
 ### 当前稳定做法（不改源码，推荐）
-- **把“任务”定义为 thread**：每个任务都在一个 thread 里推进
-- 在频道里只发“很短的 root message”当作锚点（标题/任务一句话），立刻在 thread 里继续对话
+- **把"任务"定义为 thread**：每个任务都在一个 thread 里推进
+- 在频道里只发"很短的 root message"当作锚点（标题/任务一句话），立刻在 thread 里继续对话
 - 同一频道并行多个任务：开多个 thread
 
 ### 高级（不推荐新手）：dist-level patch
@@ -39,16 +39,16 @@
 ## P1：A2A 可见性断裂（派单后 Slack thread 没有回复）
 
 ### 现象
-`sessions_send` 触发后，目标 Agent 偶尔不在预期的 Slack thread 内回复，导致用户看到“派了任务但没人做”。
+`sessions_send` 触发后，目标 Agent 偶尔不在预期的 Slack thread 内回复，导致用户看到"派了任务但没人做"。
 
 ### 当前机制：A2A 可见性契约（文档级兜底）
-OpenCrew 采用“两步触发”：
+OpenCrew 采用"两步触发"：
 1) 在目标频道创建 Slack root message（可见锚点）
 2) 用 `sessions_send` 触发目标 agent，在该 thread 的 sessionKey 内执行
 
 并要求发起方在发送后检查 thread 是否出现回复，失败则标记 `failed-delivery` 并上报。
 
-> 这是“契约兜底”，不是根治；根治需要上游在 Slack deliveryContext 方面更强的确定性。
+> 这是"契约兜底"，不是根治；根治需要上游在 Slack deliveryContext 方面更强的确定性。
 
 ---
 
@@ -64,7 +64,29 @@ OpenCrew 采用“两步触发”：
 
 ---
 
-## P2：知识系统“跨 session 语义检索”仍在探索
+## P1：飞书群聊会话隔离（OpenClaw >= 2026.3.1 已解决）
+
+### 现象
+
+飞书群聊中，同一群组内的所有对话是平铺的——没有 thread 级别的会话隔离。当一个 Agent 同时处理多个任务时，对话会混在一起。
+
+### 解决方案
+
+OpenClaw 2026.3.1 在内置飞书插件中引入了 `groupSessionScope: "group_topic"`。启用后，群组内的每个飞书话题（thread）拥有独立的会话隔离，与 Slack 的 thread 隔离行为一致。
+
+```yaml
+channels:
+  feishu:
+    groupSessionScope: "group_topic"
+```
+
+配置详情参见[飞书接入指南：groupSessionScope](FEISHU_SETUP.md#更新groupsessionscopeopenclaw--202631)。
+
+> **注意**：此功能需要使用 OpenClaw 内置飞书插件。社区插件（[AlexAnys/feishu-openclaw](https://github.com/AlexAnys/feishu-openclaw)）不支持 `groupSessionScope`。
+
+---
+
+## P2：知识系统"跨 session 语义检索"仍在探索
 
 当前 v1 依赖 Closeout + KO 提炼；跨 session 的语义检索/索引属于探索方向（欢迎贡献）。
 
diff --git a/docs/en/DISCORD_SETUP.md b/docs/en/DISCORD_SETUP.md
index 2398846..bebdcc5 100644
--- a/docs/en/DISCORD_SETUP.md
+++ b/docs/en/DISCORD_SETUP.md
@@ -129,6 +129,46 @@ Make sure the bot has "View Channel" and "Send Messages" permissions in each cha
 
 ---
 
+## Step 5b: Configure Channel Permission Isolation (Important!)
+
+> **Warning**: Without channel permission isolation, a single bot serving multiple agents may send messages in the wrong channel, causing conversations from different agents (e.g. CoS and Ops) to mix together. This was reported in [Issue #34](https://github.com/AlexAnys/opencrew/issues/34). The steps below prevent this.
+
+The core idea: the bot should only be able to **send messages** in channels that are explicitly assigned to it. At the server level, deny Send Messages; then allow it per-channel.
+
+### Single-Bot Setup (default)
+
+1. **Create a bot role** (e.g. "OpenCrew Bot"):
+   - Server Settings → Roles → Create Role
+   - **Do NOT grant Administrator** -- Administrator bypasses all channel overrides
+   - Grant these server-level permissions: `View Channels`, `Read Message History`, `Add Reactions`, `Create Public Threads`, `Create Private Threads`, `Send Messages in Threads`, `Manage Threads`
+   - **Do NOT grant** `Send Messages` at the server level
+
+2. **Assign the role to the bot**:
+   - Server Settings → Members → find the bot → add the "OpenCrew Bot" role
+
+3. **Add per-channel permission overrides** for each agent channel (`#hq`, `#cto`, `#build`, etc.):
+   - Click the channel name → Edit Channel → Permissions
+   - Click "+" to add the "OpenCrew Bot" role
+   - Set `Send Messages` to **Allow** (green checkmark)
+
+4. **Verify**: The bot should now only be able to send messages in channels where you explicitly allowed it. Test by checking that the bot cannot post in a random channel outside the agent channels.
+
+### Multi-Bot Setup
+
+If you are running multiple bots (one per agent), create a **separate role for each bot**:
+
+1. Create roles: "CoS Bot", "CTO Bot", "Builder Bot", etc.
+2. For each role: deny `Send Messages` at the server level (same as above)
+3. For each role: allow `Send Messages` only in the designated channel
+   - "CoS Bot" role → allow Send Messages only in `#hq`
+   - "CTO Bot" role → allow Send Messages only in `#cto`
+   - "Builder Bot" role → allow Send Messages only in `#build`
+4. Assign each bot its corresponding role
+
+> **Note**: This is the approach referenced in Issue #34 -- the channels are not "public" in the sense that any bot can post anywhere. Instead, you manually restrict each bot's send permission to its designated channel.
+
+---
+
 ## Step 6: Get Channel IDs (two methods)
 
 ### Method A (recommended): Enable Developer Mode and copy
@@ -167,7 +207,7 @@ Create a separate Discord Application for each agent. Each bot gets its own iden
 Things to keep in mind:
 - Each bot must be invited to the server individually
 - Bots in more than 75 servers require a separate Message Content Intent approval
-- OpenClaw multi-account support is still in development -- see [PR #3672](https://github.com/open-claw/open-claw/pull/3672)
+- OpenClaw multi-account support is available in current versions. See [Issue #3306](https://github.com/openclaw/openclaw/issues/3306) for community confirmation
 
 > **Tip**: Discord servers allow up to 50 bots. OpenCrew's 7 agents are well within this limit. For most users, a single bot with channel routing is sufficient.
 
diff --git a/docs/en/FEISHU_SETUP.md b/docs/en/FEISHU_SETUP.md
index dc9eae7..3d9fae7 100644
--- a/docs/en/FEISHU_SETUP.md
+++ b/docs/en/FEISHU_SETUP.md
@@ -20,7 +20,33 @@ Feishu does have a native "Topics" (话题) feature, but **OpenClaw's Feishu plu
 - **"Thread = task" is not available** -- all conversations within a group are flat; you cannot isolate different tasks into separate threads
 - Practical impact: when an Agent handles multiple tasks concurrently, conversations will intermingle. For light use (one task at a time) this is fine; for heavy parallel workflows it is a noticeable limitation
 
-> This is a known limitation of the OpenClaw Feishu plugin ([Issue #10242](https://github.com/openclaw/openclaw/issues/10242)), not the Feishu platform itself. Future plugin updates may resolve this.
+> This is a known limitation of the OpenClaw Feishu plugin ([Issue #29791](https://github.com/openclaw/openclaw/issues/29791)), not the Feishu platform itself.
+
+### Update: `groupSessionScope` (OpenClaw >= 2026.3.1)
+
+Starting with OpenClaw 2026.3.1, the built-in Feishu plugin supports `groupSessionScope: "group_topic"`, which enables per-topic session isolation -- equivalent to Slack's thread isolation behavior.
+
+To enable it, add `groupSessionScope` to your existing Feishu channel config (do not overwrite your other settings):
+
+```yaml
+channels:
+  feishu:
+    # ... your existing appId, appSecret, etc. ...
+    groupSessionScope: "group_topic"    # add this line
+```
+
+Or via CLI:
+
+```bash
+openclaw config set channels.feishu.groupSessionScope group_topic
+```
+
+With this setting enabled:
+- Each Feishu topic within a group chat gets its own isolated session
+- Concurrent tasks no longer intermingle
+- The behavior matches the Slack "thread = task" model
+
+> **Note**: `groupSessionScope` requires the **built-in OpenClaw Feishu plugin**. The community plugin ([AlexAnys/feishu-openclaw](https://github.com/AlexAnys/feishu-openclaw)) does not support this parameter -- you must use the built-in plugin that ships with OpenClaw >= 2026.3.1.
 
 ---
 
@@ -261,6 +287,7 @@ agents:
 - Each app needs its own event subscriptions (`im.message.receive_v1`) and permissions (see [Step 2](#step-2-configure-permissions-and-event-subscriptions))
 - In "one group per Agent" mode, add only the corresponding bot to each group to avoid duplicate messages
 - A2A communication is unaffected -- it goes through OpenClaw's internal `sessions_send`, independent of bot count
+- **Known bug**: When using multi-account mode with `SecretRef` (e.g. storing `appSecret` via a Kubernetes Secret or external secret manager), there is a known issue where credentials may not be resolved correctly on gateway restart ([OpenClaw Issue #47436](https://github.com/openclaw/openclaw/issues/47436)). Workaround: use plaintext secrets in the config file (with appropriate file permissions) until this is fixed, or restart the gateway twice after credential changes
 
 ---
 
diff --git a/docs/en/GETTING_STARTED.md b/docs/en/GETTING_STARTED.md
index 56f2db9..f7e6afd 100644
--- a/docs/en/GETTING_STARTED.md
+++ b/docs/en/GETTING_STARTED.md
@@ -8,16 +8,48 @@ This is a complete step-by-step guide. If you just want the quick path, head bac
 
 ---
 
-## Prerequisites
+## Prerequisites Checklist
 
-Before you begin, make sure:
+Before you begin, go through this checklist:
 
-- **OpenClaw is installed and working**: Running `openclaw status` shows normal output
-- **A Slack workspace is created**: You have admin permissions
-- **Basic command-line skills**: You can copy-paste and run commands in a terminal (or have your existing OpenClaw agent do it for you)
+- [ ] **OpenClaw is installed and working**: Running `openclaw status` shows normal output
+- [ ] **A messaging platform is ready**: Slack workspace, Discord server, or Feishu organization -- with admin permissions
+- [ ] **Basic command-line skills**: You can copy-paste and run commands in a terminal (or have your existing OpenClaw agent do it for you)
+- [ ] **Bot/App created on your platform**: You must create the bot/app FIRST, before connecting it to OpenClaw (see platform-specific guides below)
 
 > Not sure how to install OpenClaw? See the [OpenClaw official docs](https://docs.openclaw.ai/)
 
+### Correct Deployment Order
+
+Follow these steps in order. The most common mistake is trying to configure OpenClaw bindings before the bot is fully set up on the messaging platform.
+
+```
+Manual (you do these on the platform):
+  1. Create bot/app on your messaging platform (Discord/Slack/Feishu)
+  2. Configure permissions and intents/scopes on the platform
+  3. Invite the bot to your server/workspace/groups
+  4. Create the agent channels/groups
+
+Agent-automated (your OpenClaw agent handles these — see DEPLOY.md):
+  5. Connect the platform to OpenClaw (openclaw channels add)
+  6. Deploy OpenCrew files (shared protocols + workspaces)
+  7. Write OpenClaw config (agent bindings, channel IDs)
+  8. Restart the gateway (openclaw gateway restart)
+  9. Verify (send test messages)
+```
+
+> Steps 5-9 can be fully automated by sending the deployment prompt in [DEPLOY.md](../../DEPLOY.en.md) to your existing OpenClaw agent.
+
+### Platform-Specific Setup Guides
+
+| Platform | Setup Guide | Time Estimate |
+|----------|-------------|---------------|
+| Slack | [SLACK_SETUP.md](SLACK_SETUP.md) | ~15 min |
+| Discord | [DISCORD_SETUP.md](DISCORD_SETUP.md) | ~15 min |
+| Feishu | [FEISHU_SETUP.md](FEISHU_SETUP.md) | ~20 min |
+
+> **Tip**: Complete the platform-specific setup guide FIRST (Steps 1-4 above), then return here for Phase 2 onwards.
+
 ---
 
 ## Phase 1: Slack Setup (~20 minutes)
@@ -245,6 +277,42 @@ sudo chown -R $USER:$USER ~/.openclaw/
 
 ---
 
+## Common Mistakes
+
+These are the most frequently reported issues from new users:
+
+### 1. Wrong deployment order
+
+**Mistake**: Trying to run `openclaw channels add` or configure bindings before creating the bot on the messaging platform.
+
+**Fix**: Always create and configure the bot/app on your messaging platform first. See [Correct Deployment Order](#correct-deployment-order) above.
+
+### 2. Skipping channel permission isolation (Discord)
+
+**Mistake**: Using a single bot with default permissions, allowing it to send messages in any channel. This causes agent conversations to mix (Issue #34).
+
+**Fix**: Follow the [Channel Permission Isolation](DISCORD_SETUP.md#step-5b-configure-channel-permission-isolation-important) steps in the Discord setup guide.
+
+### 3. Forgetting to restart the gateway
+
+**Mistake**: Changing config or bindings but not restarting. Changes do not take effect until restart.
+
+**Fix**: Always run `openclaw gateway restart` after config changes, then verify with `openclaw status`.
+
+### 4. Channel ID mismatch
+
+**Mistake**: Copying the wrong Channel ID or mixing up IDs between channels.
+
+**Fix**: Double-check each Channel ID against your messaging platform. Use `openclaw channels resolve` to verify.
+
+### 5. Bot not invited to channels
+
+**Mistake**: Creating channels but forgetting to invite the bot (Slack) or add the bot role (Discord).
+
+**Fix**: In Slack, run `/invite @bot-name` in each channel. In Discord, ensure the bot role has View Channel permission. In Feishu, add the bot via group settings.
+
+---
+
 ## Quick Reference: Common Commands
 
 ```bash
diff --git a/docs/en/KNOWN_ISSUES.md b/docs/en/KNOWN_ISSUES.md
index 107ab57..754e900 100644
--- a/docs/en/KNOWN_ISSUES.md
+++ b/docs/en/KNOWN_ISSUES.md
@@ -71,6 +71,28 @@ Long-running threads with large tool outputs can cause context overflow.
 
 ---
 
+## P1: Feishu group chat session isolation (resolved in OpenClaw >= 2026.3.1)
+
+### Symptoms
+
+In Feishu group chats, all conversations within a single group are flat -- there is no thread-level session isolation. When an Agent handles multiple tasks concurrently, conversations intermingle.
+
+### Resolution
+
+OpenClaw 2026.3.1 introduced `groupSessionScope: "group_topic"` in the built-in Feishu plugin. With this setting enabled, each Feishu topic (thread) within a group gets its own isolated session, matching the Slack thread isolation behavior.
+
+```yaml
+channels:
+  feishu:
+    groupSessionScope: "group_topic"
+```
+
+See [Feishu Setup: groupSessionScope](../en/FEISHU_SETUP.md#update-groupsessionscope-openclaw--202631) for configuration details.
+
+> **Note**: This requires the built-in OpenClaw Feishu plugin. The community plugin ([AlexAnys/feishu-openclaw](https://github.com/AlexAnys/feishu-openclaw)) does not support `groupSessionScope`.
+
+---
+
 ## P2: Cross-session semantic retrieval in the knowledge system is still exploratory
 
 The current v1 relies on Closeout + KO distillation. Cross-session semantic retrieval/indexing is an exploratory direction (contributions welcome).