mirror of
https://github.com/sipeed/picoclaw.git
synced 2026-06-12 18:08:54 +00:00
BeaconCat
ba96f11f90
- Rewrite docs/channels/wecom/README.md and README.zh.md with unified 3-option setup guide (Web UI QR / CLI QR / manual config), full config table with defaults and env vars, runtime behavior details, and migration notes from legacy wecom_bot/wecom_app/wecom_aibot - Add assets/wecom-qr-binding.jpg screenshot for Web UI QR binding flow - Remove obsolete docs/channels/wecom/wecom_bot/, wecom_app/, wecom_aibot/ subdirectories (18 files, all language variants) - Update Channels table in all 8 READMEs: replace 3 legacy WeCom rows with single unified WeCom row; zh README links to README.zh.md, others link to README.md - Add Xiaomi MiMo (mimo/) to Providers table in all 8 READMEs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
149 lines
5.3 KiB
Markdown
149 lines
5.3 KiB
Markdown
> 返回 [README](../../../README.zh.md)
|
||
|
||
# 企业微信（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 内确认，凭据自动保存。
|
||
|
||
<p align="center">
|
||
<img src="../../../assets/wecom-qr-binding.jpg" alt="Web UI 企业微信扫码绑定" width="600">
|
||
</p>
|
||
|
||
### 方式二：CLI 扫码登录
|
||
|
||
运行：
|
||
|
||
```bash
|
||
picoclaw auth wecom
|
||
```
|
||
|
||
命令执行流程：
|
||
1. 向企业微信请求二维码并在终端打印
|
||
2. 同时打印一个**二维码链接**，终端二维码不清晰时可在浏览器中打开
|
||
3. 轮询确认状态——扫码后还需要在**企业微信 App 内点击确认**
|
||
4. 成功后将 `bot_id` 和 `secret` 写入 `channels.wecom` 并保存配置
|
||
|
||
默认超时为 **5 分钟**，可通过 `--timeout` 延长：
|
||
|
||
```bash
|
||
picoclaw auth wecom --timeout 10m
|
||
```
|
||
|
||
> ⚠️ 仅扫描二维码还不够——必须在企业微信 App 内点击**确认**，否则命令会超时。
|
||
|
||
### 方式三：手动配置
|
||
|
||
如果已有企业微信 AI Bot 的 `bot_id` 和 `secret`，可直接配置：
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"wecom": {
|
||
"enabled": true,
|
||
"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` 已填写且非空。
|