mirror of https://github.com/sipeed/picoclaw.git synced 2026-06-12 18:08:54 +00:00

Files

T

Hoshina c57a9c14e7 docs: sync READMEs, examples, and channel docs to match current config

- Update config.example.json to remove dead webhook_host/webhook_port
  and unused typing/placeholder fields
- Sync all READMEs (en/zh/ja/pt-br/fr/vi) with current channel config
- Update Discord docs: mention_only → group_trigger
- Update LINE, WeCom, WeComApp channel docs

2026-02-28 22:25:37 +08:00

3.1 KiB

Raw Blame History

企业微信自建应用 (WeCom App) 配置指南

本文档介绍如何在 PicoClaw 中配置企业微信自建应用 (wecom-app) 通道。

功能特性

功能	支持状态
被动接收消息	✅
主动发送消息	✅
私聊	✅
群聊	❌

配置步骤

1. 企业微信后台配置

登录企业微信管理后台
进入"应用管理" → 选择自建应用
记录以下信息：
- AgentId: 应用详情页显示
- Secret: 点击"查看"获取
进入"我的企业"页面，记录 企业ID (CorpID)

2. 接收消息配置

在应用详情页，点击"接收消息"的"设置API接收"
填写以下信息：
- URL: http://your-server:18790/webhook/wecom-app
- Token: 随机生成或自定义（用于签名验证）
- EncodingAESKey: 点击"随机生成"生成43字符的密钥
点击"保存"时，企业微信会发送验证请求

3. PicoClaw 配置

在 config.json 中添加以下配置：

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",           // 企业ID
      "corp_secret": "xxxxxxxxxxxxxxxxxxxxxxxx", // 应用Secret
      "agent_id": 1000002,                        // 应用AgentId
      "token": "your_token",                      // 接收消息配置的Token
      "encoding_aes_key": "your_encoding_aes_key", // 接收消息配置的EncodingAESKey
      "webhook_path": "/webhook/wecom-app",
      "allow_from": [],
      "reply_timeout": 5
    }
  }
}

常见问题

1. 回调URL验证失败

症状: 企业微信保存API接收消息时提示验证失败

检查项:

确认服务器防火墙已开放 Gateway 端口（默认 18790）
确认 corp_id、token、encoding_aes_key 配置正确
查看 PicoClaw 日志是否有请求到达

2. 中文消息解密失败

症状: 发送中文消息时出现 invalid padding size 错误

原因: 企业微信使用非标准的 PKCS7 填充（32字节块大小）

解决: 确保使用最新版本的 PicoClaw，已修复此问题。

3. 端口冲突

症状: 启动时提示端口已被占用

解决: 修改 gateway.port 为其他端口（所有 Webhook 渠道共享同一个 Gateway HTTP 服务器）

技术细节

加密算法

算法: AES-256-CBC
密钥: EncodingAESKey Base64解码后的32字节
IV: AESKey的前16字节
填充: PKCS7（块大小为32字节，非标准16字节）
消息格式: XML

消息结构

解密后的消息格式：

random(16B) + msg_len(4B) + msg + receiveid

其中 receiveid 对于自建应用是 corp_id。

调试

启用调试模式查看详细日志：

picoclaw gateway --debug

关键日志标识：

wecom_app: WeCom App 通道相关日志
wecom_common: 加密解密相关日志

3.1 KiB Raw Blame History Unescape Escape