移动端接入

Wesclaw 支持通过多种 IM 平台进行移动端接入。配置完成后，你可以在手机上通过企业微信、飞书、钉钉等平台与 AI 助手对话。

概览

支持的 IM 平台

平台支持状态接入方式
企业微信✅ 完整支持应用消息 + Webhook
飞书✅ 完整支持机器人应用
钉钉✅ 完整支持企业内部应用
微信公众号✅ 支持服务号消息
其他平台🔌 可扩展通过 Webhook 或 MCP

前置条件

企业微信接入配置

步骤一：创建企业微信应用

  1. 登录 企业微信管理后台
  2. 进入「应用管理 → 自建应用 → 创建应用」
  3. 填写应用名称（如「AI 助手」）和可见范围
  4. 记录以下信息：
    • Corp ID（企业 ID）：在「我的企业」页面查看
    • Agent ID（应用 ID）：创建应用后显示
    • Secret（应用密钥）：创建应用后显示

步骤二：配置回调 URL

在应用设置中：

  1. 进入「接收消息 → 设置 API 接收」
  2. 填写 URL：https://your-domain.com/cells/main/webhook/wecom
  3. 填写 Token 和 EncodingAESKey（自动生成即可）
  4. 点击保存

步骤三：在 Wesclaw 中配置

在 config.yaml 中添加：

channels:
  - type: wecom
    corp_id: "wxXXXXXXXX"
    agent_id: 1000001
    secret_ref:
      source: env
      value: WECOM_SECRET
    token: "your-callback-token"
    encoding_aes_key: "your-encoding-aes-key"

设置环境变量：

export WECOM_SECRET="your-app-secret"

步骤四：验证

  1. 重启 Wesclaw
  2. 在企业微信中找到你创建的应用
  3. 发送一条消息，确认收到 AI 回复

企业微信群聊

除了单聊，还支持在企业微信群中使用：

  1. 将应用机器人添加到群聊
  2. 在群中 @机器人 发送消息
  3. 机器人只回复 @ 它的消息

飞书机器人配置

步骤一：创建飞书应用

  1. 登录 飞书开放平台
  2. 创建企业自建应用
  3. 在「权限管理」中开启消息相关权限
  4. 记录 App ID 和 App Secret

步骤二：配置事件订阅

  1. 在应用设置中进入「事件订阅」
  2. 填写请求地址：https://your-domain.com/cells/main/webhook/feishu
  3. 添加事件：im.message.receive_v1（接收消息）
  4. 添加事件：im.chat.member.bot.added_v1（机器人入群）

步骤三：在 Wesclaw 中配置

channels:
  - type: feishu
    app_id_ref:
      source: env
      value: FEISHU_APP_ID
    app_secret_ref:
      source: env
      value: FEISHU_APP_SECRET
    verification_token: "your-verification-token"

步骤四：发布应用

  1. 在飞书开放平台提交应用审核
  2. 审核通过后发布
  3. 在飞书中搜索你的应用开始对话

钉钉集成

步骤一：创建钉钉应用

  1. 登录 钉钉开放平台
  2. 创建企业内部应用
  3. 在「机器人与消息推送」中配置
  4. 记录 AppKey 和 AppSecret

步骤二：配置消息接收

  1. 在机器人设置中配置消息接收地址
  2. URL：https://your-domain.com/cells/main/webhook/dingtalk
  3. 开启消息接收开关

步骤三：在 Wesclaw 中配置

channels:
  - type: dingtalk
    app_key_ref:
      source: env
      value: DINGTALK_APP_KEY
    app_secret_ref:
      source: env
      value: DINGTALK_APP_SECRET

步骤四：验证

  1. 重启 Wesclaw
  2. 在钉钉中找到机器人
  3. 发送消息测试

微信公众号

配置方式

微信公众号接入需要服务号（订阅号不支持自动回复 API）。

  1. 登录 微信公众平台
  2. 在「开发 → 基本配置」中获取 AppID 和 AppSecret
  3. 配置服务器地址和 Token
channels:
  - type: weixin
    app_id_ref:
      source: env
      value: WEIXIN_APP_ID
    app_secret_ref:
      source: env
      value: WEIXIN_APP_SECRET
    token: "your-token"

限制

其他 IM 平台

通过 Webhook 接入

对于不直接支持的 IM 平台，可以通过通用 Webhook 方式接入：

  1. 在目标平台创建机器人/应用
  2. 配置 Webhook 回调到 Wesclaw
  3. 实现消息格式转换

通过 MCP 接入

使用 MCP（Model Context Protocol）服务器作为桥接：

  1. 开发或使用现有的 MCP 服务器
  2. 在 Wesclaw 中注册 MCP 连接
  3. MCP 服务器负责与 IM 平台通信

通用配置说明

Webhook 安全

所有 Webhook 回调都支持签名验证：

确保在配置中正确设置验证参数，防止伪造请求。

消息格式

IM 渠道中的消息与桌面版/云端版略有不同：

多渠道同步

同一个 Cell 可以同时接入多个 IM 渠道。对话上下文按 session 隔离：

故障排查

常见问题

问题可能原因解决方案
收不到消息Webhook URL 不可达检查公网访问和防火墙
回复超时AI 生成时间过长使用更快的模型
认证失败密钥配置错误检查 Secret / Token 配置
消息乱码编码问题确认 UTF-8 编码

测试工具

# 测试 Webhook 连通性
curl -X POST https://your-domain.com/cells/main/webhook/wecom \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

注意事项

  1. 公网访问：IM 平台的回调需要公网可访问的 URL，本地开发可使用 ngrok 等工具
  2. HTTPS 必须：大部分 IM 平台要求回调 URL 使用 HTTPS
  3. 消息频率：注意各平台的 API 调用频率限制
  4. 凭证安全：IM 平台的密钥不要硬编码在代码中，使用环境变量或密钥管理服务
  5. 多实例注意：同一套 IM 凭证不能在多个 Wesclaw 实例中使用

相关文档