返回 README

企业微信（WeCom）

PicoClaw 将企业微信整合为单一的 channels.wecom 渠道，基于腾讯官方企业微信 AI Bot WebSocket API 实现。原有的 wecom、wecom_app、wecom_aibot 三个独立渠道已合并为统一配置模型。

本渠道无需公网 Webhook 回调地址。PicoClaw 主动向企业微信建立出站 WebSocket 连接。

支持的功能

单聊和群聊消息收发
基于企业微信 AI Bot 协议的流式回复
接收文本、语音、图片、文件、视频及混合消息
发送文本及媒体消息（image、file、voice、video）
通过 Web UI 或 CLI 扫码绑定
发送者白名单和 reasoning_channel_id 路由

快速开始

方式一：Web UI 扫码绑定（推荐）

打开 Web UI，进入 Channels → WeCom，点击扫码绑定按钮。用企业微信扫码并在 App 内确认，凭据自动保存。

方式二：CLI 扫码登录

运行：

bash

picoclaw auth wecom

命令执行流程：

向企业微信请求二维码并在终端打印
同时打印一个二维码链接，终端二维码不清晰时可在浏览器中打开
轮询确认状态——扫码后还需要在企业微信 App 内点击确认
成功后将 bot_id 和 secret 写入 channels.wecom 并保存配置

默认超时为 5 分钟，可通过 --timeout 延长：

bash

picoclaw auth wecom --timeout 10m

⚠️ 仅扫描二维码还不够——必须在企业微信 App 内点击确认，否则命令会超时。

方式三：手动配置

如果已有企业微信 AI Bot 的 bot_id 和 secret，可直接配置：

json

{
  "channel_list": {
    "wecom": {
      "enabled": true,
      "type": "wecom",
      "bot_id": "YOUR_BOT_ID",
      "secret": "YOUR_SECRET",
      "websocket_url": "wss://openws.work.weixin.qq.com",
      "send_thinking_message": true,
      "allow_from": [],
      "reasoning_channel_id": ""
    }
  }
}

配置项说明

字段	类型	默认值	说明
`enabled`	bool	`false`	启用企业微信渠道。
`bot_id`	string	—	企业微信 AI Bot 标识符。启用时必填。
`secret`	string	—	企业微信 AI Bot 密钥。加密存储于 `.security.yml`。启用时必填。
`websocket_url`	string	`wss://openws.work.weixin.qq.com`	企业微信 WebSocket 端点。
`send_thinking_message`	bool	`true`	在流式回复开始前发送"处理中..."提示消息。
`allow_from`	array	`[]`	发送者白名单。为空时允许所有人。
`reasoning_channel_id`	string	`""`	可选，将推理/思考内容路由到指定会话 ID。

环境变量

所有字段均可通过 PICOCLAW_CHANNELS_WECOM_ 前缀的环境变量覆盖：

环境变量	对应字段
`PICOCLAW_CHANNELS_WECOM_ENABLED`	`enabled`
`PICOCLAW_CHANNELS_WECOM_BOT_ID`	`bot_id`
`PICOCLAW_CHANNELS_WECOM_SECRET`	`secret`
`PICOCLAW_CHANNELS_WECOM_WEBSOCKET_URL`	`websocket_url`
`PICOCLAW_CHANNELS_WECOM_SEND_THINKING_MESSAGE`	`send_thinking_message`
`PICOCLAW_CHANNELS_WECOM_ALLOW_FROM`	`allow_from`
`PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID`	`reasoning_channel_id`

运行时行为

PicoClaw 维护活跃的企业微信 Turn，流式回复尽可能在同一流上继续。
流式回复最大持续时长为 5.5 分钟，最小发送间隔为 500ms。
流式不可用时，回复降级为主动推送。
会话路由关联在 30 分钟无活动后过期。
接收到的媒体文件先下载到本地媒体存储，再传递给 Agent。
发送媒体时先上传为企业微信临时文件，再作为媒体消息发送。
自动检测并过滤重复消息（环形缓冲区，最多记录 1000 条消息 ID）。

从旧版企业微信配置迁移

旧配置	迁移方式
`channels.wecom`（Webhook 机器人）	改用 `channels.wecom`，填写 `bot_id` + `secret`。
`channels.wecom_app`	删除，改用 `channels.wecom`。
`channels.wecom_aibot`	将 `bot_id` 和 `secret` 移至 `channels.wecom`。
`token`、`encoding_aes_key`、`webhook_url`、`webhook_path`	已废弃，从配置中删除。
`corp_id`、`corp_secret`、`agent_id`	已废弃，从配置中删除。
`welcome_message`、`processing_message`、`max_steps`	已不属于企业微信渠道配置，删除即可。

常见问题

扫码绑定超时

扫码后必须在企业微信 App 内点击确认，仅扫码不够。
使用更长的超时重试：picoclaw auth wecom --timeout 10m
终端二维码不清晰时，使用命令打印的二维码链接在浏览器中打开。

二维码已过期

二维码有效期有限，重新运行 picoclaw auth wecom 获取新二维码。

WebSocket 连接失败

检查 bot_id 和 secret 是否正确。
确认设备可以访问 wss://openws.work.weixin.qq.com（出站 WebSocket，无需开放入站端口）。

收不到回复

检查 allow_from 是否屏蔽了发送者。
确认 channels.wecom.bot_id 和 channels.wecom.secret 已填写且非空。