IM 渠道集成

Wesclaw 支持与企业微信、飞书、钉钉等主流 IM 平台集成，让 AI 助手直接在你的工作沟通工具中为你服务。

概述

通过 IM 渠道集成，你可以：

• 在企业微信/飞书/钉钉中直接与 AI 助手对话
• 在群聊中 @AI 助手获取帮助
• 接收 AI 助手的定时通知和任务提醒
• 让 AI 助手自动回复常见问题

支持平台

企业微信

前置条件

1. 拥有企业微信管理员权限
2. 已创建企业微信自建应用

创建应用

1. 登录 企业微信管理后台
2. 进入「应用管理」→「自建」→「创建应用」
3. 填写应用信息：
   • 应用名称：AI 助手（可自定义）
   • 应用 Logo：上传你喜欢的图标
   • 可见范围：选择需要使用的部门或成员

获取凭证

创建应用后，记录以下信息：

配置回调

1. 在应用详情页，找到「接收消息」→「设置API接收」
2. 填写：
   • URL：https://你的域名/cells/{cellID}/webhook/wecom
   • Token：自动生成或手动输入
   • EncodingAESKey：自动生成或手动输入
3. 点击「保存」，企业微信会发送验证请求

在 Wesclaw 中配置

桌面端：进入「设置」→「渠道」→「添加企业微信」

填写上述获取的凭证信息：

渠道类型: 企业微信
Corp ID: wxxxxxxx
Agent ID: 1000001
Secret: xxxxxxxxxxxxxx

配置完成后，企业微信中该应用即可作为 AI 助手使用。

飞书

前置条件

1. 拥有飞书开放平台开发者权限
2. 已创建飞书自建应用

创建应用

1. 登录 飞书开放平台
2. 进入「开发者后台」→「创建企业自建应用」
3. 填写应用信息

获取凭证

配置事件订阅

1. 进入「事件与回调」→「事件配置」
2. 配置请求地址：https://你的域名/cells/{cellID}/webhook/feishu
3. 添加事件：
   • im.message.receive_v1（接收消息）
4. 在「权限管理」中开通：
   • im:message（获取与发送单聊、群聊消息）
   • im:message.group_at_msg（接收群聊中 @ 机器人消息）

在 Wesclaw 中配置

渠道类型: 飞书
App ID: cli_xxxxxxxxxx
App Secret: xxxxxxxxxxxxxx

飞书特有功能

• 消息卡片：AI 回复支持飞书交互式消息卡片
• 富文本：支持发送富文本格式的回复
• 文件分享：可以直接在对话中发送文件

钉钉

前置条件

1. 拥有钉钉开发者权限
2. 已创建钉钉企业内部应用

创建应用

1. 登录 钉钉开放平台
2. 进入「应用开发」→「企业内部开发」→「创建应用」
3. 填写应用信息

获取凭证

配置消息接收

1. 进入「机器人与消息推送」
2. 配置消息接收地址：https://你的域名/cells/{cellID}/webhook/dingtalk
3. 开启机器人配置

在 Wesclaw 中配置

渠道类型: 钉钉
App Key: dingxxxxxxxxxx
App Secret: xxxxxxxxxxxxxx

配置流程

通用配置步骤

无论选择哪个 IM 平台，配置流程大致相同：

1. 在 IM 平台创建应用/机器人
           ↓
2. 获取应用凭证（ID + Secret）
           ↓
3. 配置消息回调 URL
           ↓
4. 在 Wesclaw 设置中填入凭证
           ↓
5. 验证连接是否正常
           ↓
6. 配置消息处理规则

网络要求

IM 平台的回调需要公网可访问的 URL：

• 桌面端：需要通过内网穿透工具（如 ngrok、frp）或部署在有公网 IP 的服务器
• SaaS 版：平台已提供公网回调地址，直接使用即可

多渠道管理

你可以同时配置多个 IM 渠道，每个渠道独立工作：

消息格式

支持的消息类型

消息长度限制

不同平台有不同的消息长度限制：

群聊交互规则

在群聊中使用 AI 助手时：

• 需要 @机器人 才会触发回复
• 回复会在群内可见
• 支持引用消息进行追问
• 每个群成员的对话上下文独立管理

安全注意事项

1. 凭证保管：应用的 Secret 等同于密码，请妥善保管
2. 权限最小化：只授予 AI 助手必要的权限
3. IP 白名单：如平台支持，建议配置 IP 白名单
4. 消息加密：确保回调 URL 使用 HTTPS
5. 日志审计：定期检查 AI 助手的消息记录

常见问题

回调验证失败

现象：配置回调 URL 后提示验证失败。

排查：

1. 确认 URL 是否公网可访问
2. 检查 Token 和 EncodingAESKey 是否正确
3. 查看服务端日志是否收到验证请求

消息发送延迟

现象：在 IM 中发消息后，回复较慢。

可能原因：

• AI 模型处理需要时间（尤其是复杂任务）
• 网络延迟
• 消息队列积压

群聊中不回复

现象：在群聊中 @机器人，但没有回复。

排查：

1. 确认应用权限包含群聊消息接收
2. 检查是否正确 @了机器人（而非文字提及）
3. 查看是否有消息过滤规则拦截