# 渠道开通与排查

开通微信、飞书、企业微信、钉钉等渠道，配置绑定模式、成员映射、渠道活动和会话排查。

渠道把微信、飞书、企业微信、钉钉等外部入口连接到工作区。渠道配置完成后，外部消息才能进入正确工作区，并路由到项目、智能体、数字员工或工作流。

## 支持渠道

工作区渠道页支持常见渠道：

| 渠道   | 用途                   |
| ---- | -------------------- |
| 飞书   | 接入飞书机器人或应用消息。        |
| 微信   | 接入微信 iLink Bot 通道消息。 |
| 企业微信 | 接入企业微信应用消息与回调。       |
| 钉钉   | 接入钉钉机器人或应用消息。        |

不同渠道需要的凭据和回调配置不同。生产配置应保存到模块属性或渠道配置中，不要写在页面文案或公开代码里。

## 开通渠道

开通渠道的一般步骤：

1. 进入目标工作区，打开「渠道」页。
2. 选择要接入的渠道类型。
3. 安装包含对应渠道模块的 Bundle，或确认该 Bundle 已在目标 Runtime 物化模块。
4. 填写渠道属性，例如应用 ID、secret、token、回调参数。
5. 安装或确认 `channel-gateway`。
6. 设置渠道启用状态、绑定模式和默认路由。
7. 从外部渠道发送一条真实消息。
8. 在渠道活动和会话中确认消息进入。

## 微信自助开通

微信自助开通通常通过二维码完成。开通时需要：

- 生成登录二维码。
- 用目标微信扫码。
- 等待绑定状态完成。
- 确认工作区中出现微信渠道配置。
- 发送测试消息确认默认用户或成员绑定正确。

微信适合个人助理或默认单用户入口。多人或组织场景要特别确认绑定模式。

## 飞书开通

飞书开通通常通过授权会话完成。开通时需要：

- 创建飞书 onboarding session。
- 打开验证链接或输入 user code。
- 等待授权状态完成。
- 确认应用 ID、租户和 worker 状态。
- 在飞书中发送测试消息。

如果授权完成但消息不进平台，先看飞书事件订阅和渠道启用状态，再看 channel-gateway 活动。

## 绑定模式

渠道消息进入后，需要映射到工作区内部用户或项目。

常见绑定模式：

| 模式     | 用途                            |
| ------ | ----------------------------- |
| 按发送人绑定 | 每个外部发送人绑定到一个内部用户。适合团队协作。      |
| 默认用户   | 所有消息按一个默认内部用户处理。适合个人助理或单入口场景。 |

绑定错误会导致智能体上下文、权限、项目访问和消息归属异常。排查时优先查看渠道绑定列表。

## 渠道活动与会话

渠道页会展示活动、绑定和配置状态。渠道会话页用于查看消息会话，适合排查：

- 外部消息是否进入平台。
- 消息进入了哪个工作区。
- 绑定到了哪个内部用户。
- 触发了哪个项目、智能体或工作流。
- 是否被过滤为工具事件或增量事件。

## 常见问题

| 问题        | 排查顺序                                                      |
| --------- | --------------------------------------------------------- |
| 外部消息没有进入  | 渠道是否启用、回调地址、channel-gateway、渠道活动。                         |
| 消息进入但无人回复 | 绑定模式、默认用户、默认项目、智能体配置。                                     |
| 回复到了错误成员  | 外部发送人绑定、内部用户映射、工作区是否正确。                                   |
| 企微回调失败    | `corpId`、`corpSecret`、`agentId`、`token`、`encodingAesKey`。 |
| 飞书授权后不可用  | onboarding 状态、租户 ID、事件订阅、worker 状态。                       |
| 微信扫码后不可用  | 登录状态、默认用户、iLink Bot 状态、渠道启用状态。                            |

## 发布前检查

上线渠道前，至少完成：

1. 包含渠道模块的 Bundle 已安装到目标工作区，且模块已在目标 Runtime 物化成功。
2. `channel-gateway` 已安装并配置。
3. 渠道启用状态正确。
4. 默认项目、默认用户或发送人绑定正确。
5. 外部渠道发送消息后，渠道活动能看到记录。
6. 智能体、工作流或项目能收到并处理消息。