diff --git a/docs/channels/wecom/README.md b/docs/channels/wecom/README.md
new file mode 100644
index 000000000..ecdfbc47b
--- /dev/null
+++ b/docs/channels/wecom/README.md
@@ -0,0 +1,104 @@
+> Back to [README](../../../README.md)
+
+# WeCom
+
+PicoClaw now exposes WeCom as a single `channels.wecom` channel built on the official WeCom AI Bot WebSocket API.
+This replaces the legacy `wecom`, `wecom_app`, and `wecom_aibot` split with one configuration model.
+
+## What This Channel Supports
+
+- Direct chat and group chat delivery
+- Channel-side streaming replies over WeCom's AI Bot protocol
+- Incoming text, voice, image, file, video, and mixed messages
+- Outbound text and media replies (`image`, `file`, `voice`, `video`)
+- QR-based CLI onboarding with `picoclaw auth wecom`
+- Shared allowlist and `reasoning_channel_id` routing
+
+> No public webhook callback URL is required for this channel. PicoClaw opens an outbound WebSocket connection to WeCom.
+
+## Quick Start
+
+### Option 1: QR Login From CLI
+
+Run:
+
+```bash
+picoclaw auth wecom
+```
+
+The command prints a QR code in the terminal, waits for confirmation in WeCom, and then writes the resulting
+`bot_id` and `secret` into `channels.wecom`.
+
+Use `--timeout` if you want to wait longer:
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+### Option 2: Configure Manually
+
+```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": ""
+ }
+ }
+}
+```
+
+## Configuration
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `enabled` | bool | No | Enables the WeCom channel. |
+| `bot_id` | string | Yes | WeCom AI Bot identifier. Required when the channel is enabled. |
+| `secret` | string | Yes | WeCom AI Bot secret. Required when the channel is enabled. |
+| `websocket_url` | string | No | WebSocket endpoint. Defaults to `wss://openws.work.weixin.qq.com`. |
+| `send_thinking_message` | bool | No | Sends an initial `Processing...` chunk before the final streamed reply. Defaults to `true`. |
+| `allow_from` | array | No | Sender allowlist. Empty means allow all senders. |
+| `reasoning_channel_id` | string | No | Optional destination for reasoning/thinking output. |
+
+## Runtime Behavior
+
+- PicoClaw keeps the active WeCom turn so normal replies can continue the same stream when possible.
+- If streaming is no longer available, replies fall back to active push delivery to the resolved chat route.
+- Incoming media is downloaded into the media store before being handed to the agent.
+- Outbound media is uploaded to WeCom in temporary chunks and then sent as a regular media message.
+
+## Migration Notes
+
+This branch removes the old multi-channel WeCom model.
+
+| Previous config | Now |
+| --------------- | --- |
+| `channels.wecom` webhook bot | Replace with `channels.wecom` using `bot_id` + `secret`. |
+| `channels.wecom_app` | Remove it and use `channels.wecom`. |
+| `channels.wecom_aibot` | Move the config to `channels.wecom`. |
+| `token`, `encoding_aes_key`, `webhook_url`, `webhook_path` | No longer used by the WeCom channel. |
+| `corp_id`, `corp_secret`, `agent_id` | No longer used by the WeCom channel. |
+| `welcome_message`, `processing_message`, `max_steps` under WeCom | No longer part of the WeCom channel config. |
+
+## Troubleshooting
+
+### `picoclaw auth wecom` times out
+
+- Re-run with a larger `--timeout`.
+- Make sure the QR code was confirmed inside WeCom, not only scanned.
+
+### WebSocket connection fails
+
+- Verify `bot_id` and `secret`.
+- Confirm the host can reach `wss://openws.work.weixin.qq.com`.
+
+### Replies do not arrive
+
+- Check whether `allow_from` blocks the sender.
+- Check launcher or startup validation for missing `channels.wecom.bot_id` / `channels.wecom.secret`.
+
diff --git a/docs/channels/wecom/README.zh.md b/docs/channels/wecom/README.zh.md
new file mode 100644
index 000000000..6b4a5e495
--- /dev/null
+++ b/docs/channels/wecom/README.zh.md
@@ -0,0 +1,104 @@
+> 返回 [README](../../../README.zh.md)
+
+# 企业微信
+
+PicoClaw 现在将企业微信统一为一个 `channels.wecom` 渠道，并基于企业微信官方 AI Bot WebSocket 协议实现。
+这取代了旧的 `wecom`、`wecom_app`、`wecom_aibot` 三套配置模型。
+
+## 当前渠道能力
+
+- 支持私聊和群聊
+- 支持企业微信侧流式回复
+- 支持接收文本、语音、图片、文件、视频和 mixed 消息
+- 支持发送文本与媒体消息（`image`、`file`、`voice`、`video`）
+- 支持通过 `picoclaw auth wecom` 扫码写入配置
+- 支持统一白名单与 `reasoning_channel_id`
+
+> 这个渠道不再需要公网 webhook 回调地址。PicoClaw 会主动向企业微信发起 WebSocket 连接。
+
+## 快速开始
+
+### 方式 1：命令行扫码登录
+
+运行：
+
+```bash
+picoclaw auth wecom
+```
+
+该命令会在终端打印二维码，等待你在企业微信中确认，然后把生成的 `bot_id` 和 `secret` 写入
+`channels.wecom`。
+
+如果需要更长等待时间，可以加 `--timeout`：
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+### 方式 2：手动配置
+
+```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 | 否 | 是否启用企业微信渠道。 |
+| `bot_id` | string | 是 | 企业微信 AI Bot 标识。渠道启用时必填。 |
+| `secret` | string | 是 | 企业微信 AI Bot 密钥。渠道启用时必填。 |
+| `websocket_url` | string | 否 | WebSocket 地址，默认 `wss://openws.work.weixin.qq.com`。 |
+| `send_thinking_message` | bool | 否 | 是否在流式最终回复前先发送一段 `Processing...` 开场消息，默认 `true`。 |
+| `allow_from` | array | 否 | 发送者白名单；空数组表示允许所有发送者。 |
+| `reasoning_channel_id` | string | 否 | 可选的 reasoning/thinking 输出目标。 |
+
+## 运行时行为
+
+- PicoClaw 会保留当前会话对应的企业微信 turn，优先继续同一个流式回复。
+- 如果流式上下文已经失效，回复会自动回退到主动推送消息。
+- 收到的媒体会先下载到 media store，再交给 Agent 处理。
+- 发出的媒体会先按分片上传到企业微信，再作为普通媒体消息发送。
+
+## 迁移说明
+
+这个分支移除了旧的多通道企业微信模型。
+
+| 旧配置 | 现在怎么做 |
+| ------ | ---------- |
+| `channels.wecom` webhook 机器人 | 改为使用 `bot_id` + `secret` 的 `channels.wecom`。 |
+| `channels.wecom_app` | 删除，统一迁移到 `channels.wecom`。 |
+| `channels.wecom_aibot` | 配置迁移到 `channels.wecom`。 |
+| `token`、`encoding_aes_key`、`webhook_url`、`webhook_path` | 企业微信渠道不再使用这些字段。 |
+| `corp_id`、`corp_secret`、`agent_id` | 企业微信渠道不再使用这些字段。 |
+| 企业微信下的 `welcome_message`、`processing_message`、`max_steps` | 不再属于企业微信渠道配置。 |
+
+## 常见问题
+
+### `picoclaw auth wecom` 超时
+
+- 用更大的 `--timeout` 重新执行。
+- 确认是在企业微信里完成了确认，而不只是扫描二维码。
+
+### WebSocket 连接失败
+
+- 检查 `bot_id` 和 `secret` 是否正确。
+- 确认运行环境可以访问 `wss://openws.work.weixin.qq.com`。
+
+### 消息没有回到企业微信
+
+- 检查 `allow_from` 是否拦截了发送者。
+- 检查启动日志或 launcher 校验，确认 `channels.wecom.bot_id` / `channels.wecom.secret` 已填写。
+
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 4a78f465e..3d01994ff 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -6,7 +6,7 @@
Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, or Pico (native protocol)
-> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
+> **Note**: Channels that rely on HTTP callbacks share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Socket/stream-based channels such as Feishu, DingTalk, and WeCom do not rely on the shared webhook server for inbound delivery.
| Channel | Difficulty | Description | Documentation |
| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -19,7 +19,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,
| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](channels/qq/README.md) |
| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](channels/dingtalk/README.md) |
| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](channels/line/README.md) |
-| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](channels/wecom/wecom_bot/README.md) / [App](channels/wecom/wecom_app/README.md) / [AI Bot](channels/wecom/wecom_aibot/README.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Official AI Bot over WebSocket, streaming + media | [Docs](channels/wecom/README.md) |
| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](channels/feishu/README.md) |
| **IRC** | ⭐⭐ Medium | Server + TLS configuration | [Docs](#irc) |
| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](channels/onebot/README.md) |
@@ -380,102 +380,34 @@ picoclaw gateway
WeCom (企业微信)
-PicoClaw supports three types of WeCom integration:
+PicoClaw now exposes WeCom as a single AI Bot channel over WebSocket.
+No public webhook callback URL is required.
-**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats
-**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only
-**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat
+See [WeCom Configuration Guide](channels/wecom/README.md) for the full configuration reference and migration notes.
-See [WeCom AI Bot Configuration Guide](channels/wecom/wecom_aibot/README.md) for detailed setup instructions.
+**Quick Setup - Recommended**
-**Quick Setup - WeCom Bot:**
+**1. Authenticate**
-**1. Create a bot**
+```bash
+picoclaw auth wecom
+```
-* Go to WeCom Admin Console → Group Chat → Add Group Bot
-* Copy the webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+This command shows a QR code, waits for approval in WeCom, and writes `bot_id` + `secret` into `channels.wecom`.
-**2. Configure**
+**2. Configure manually if needed**
```json
{
"channels": {
"wecom": {
"enabled": true,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
- "webhook_path": "/webhook/wecom",
- "allow_from": []
- }
- }
-}
-```
-
-> WeCom webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
-
-**Quick Setup - WeCom App:**
-
-**1. Create an app**
-
-* Go to WeCom Admin Console → App Management → Create App
-* Copy **AgentId** and **Secret**
-* Go to "My Company" page, copy **CorpID**
-
-**2. Configure receive message**
-
-* In App details, click "Receive Message" → "Set API"
-* Set URL to `http://your-server:18790/webhook/wecom-app`
-* Generate **Token** and **EncodingAESKey**
-
-**3. Configure**
-
-```json
-{
- "channels": {
- "wecom_app": {
- "enabled": true,
- "corp_id": "wwxxxxxxxxxxxxxxxx",
- "corp_secret": "YOUR_CORP_SECRET",
- "agent_id": 1000002,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_path": "/webhook/wecom-app",
- "allow_from": []
- }
- }
-}
-```
-
-**4. Run**
-
-```bash
-picoclaw gateway
-```
-
-> **Note**: WeCom webhook callbacks are served on the Gateway port (default 18790). Use a reverse proxy for HTTPS.
-
-**Quick Setup - WeCom AI Bot:**
-
-**1. Create an AI Bot**
-
-* Go to WeCom Admin Console → App Management → AI Bot
-* In the AI Bot settings, configure callback URL: `http://your-server:18790/webhook/wecom-aibot`
-* Copy **Token** and click "Random Generate" for **EncodingAESKey**
-
-**2. Configure**
-
-```json
-{
- "channels": {
- "wecom_aibot": {
- "enabled": true,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
- "webhook_path": "/webhook/wecom-aibot",
+ "bot_id": "YOUR_BOT_ID",
+ "secret": "YOUR_SECRET",
+ "websocket_url": "wss://openws.work.weixin.qq.com",
+ "send_thinking_message": true,
"allow_from": [],
- "welcome_message": "Hello! How can I help you?",
- "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+ "reasoning_channel_id": ""
}
}
}
@@ -487,7 +419,7 @@ picoclaw gateway
picoclaw gateway
```
-> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery.
+> Legacy `wecom_app` and `wecom_aibot` entries are replaced by the unified `channels.wecom` config in this branch.
diff --git a/docs/zh/chat-apps.md b/docs/zh/chat-apps.md
index 4d1451d68..47add38ac 100644
--- a/docs/zh/chat-apps.md
+++ b/docs/zh/chat-apps.md
@@ -6,7 +6,7 @@
PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
-> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。
+> **注意**: 依赖 HTTP 回调的渠道共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。飞书、钉钉、企业微信这类 Socket/Stream 模式渠道不依赖共享 webhook 服务器来接收入站消息。
### 核心渠道
@@ -21,7 +21,7 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方
| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](../channels/qq/README.zh.md) |
| **钉钉 (DingTalk)** | ⭐⭐ 中等 | Stream 模式无需公网，企业办公首选 | [查看文档](../channels/dingtalk/README.zh.md) |
| **LINE** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](../channels/line/README.zh.md) |
-| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](../channels/wecom/wecom_bot/README.zh.md) / [App 文档](../channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](../channels/wecom/wecom_aibot/README.zh.md) |
+| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 官方 AI Bot WebSocket 接入，支持流式回复和媒体消息 | [查看文档](../channels/wecom/README.zh.md) |
| **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作，功能丰富 | [查看文档](../channels/feishu/README.zh.md) |
| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | [查看文档](#irc) |
| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](../channels/onebot/README.zh.md) |
@@ -492,102 +492,34 @@ picoclaw gateway
企业微信 (WeCom)
-PicoClaw 支持三种企业微信集成方式：
+PicoClaw 现在将企业微信统一为一个基于 WebSocket 的 AI Bot 渠道。
+它不再需要公网 webhook 回调地址。
-**方式 1: 群机器人 (Bot)** — 设置简单，支持群聊
-**方式 2: 自建应用 (App)** — 功能更多，支持主动推送，仅私聊
-**方式 3: 智能机器人 (AI Bot)** — 官方 AI Bot，流式回复，支持群聊和私聊
+完整配置说明和迁移说明请参考 [企业微信配置指南](../channels/wecom/README.zh.md)。
-详细设置请参考 [企业微信 AI Bot 配置指南](../channels/wecom/wecom_aibot/README.zh.md)。
+**推荐快速接入**
-**快速设置 — 群机器人：**
+**1. 认证**
-**1. 创建 Bot**
+```bash
+picoclaw auth wecom
+```
-* 企业微信管理后台 → 群聊 → 添加群机器人
-* 复制 Webhook URL（格式：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`）
+该命令会显示二维码，等待你在企业微信里确认，然后把 `bot_id` 和 `secret` 写入 `channels.wecom`。
-**2. 配置**
+**2. 如需手动配置**
```json
{
"channels": {
"wecom": {
"enabled": true,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
- "webhook_path": "/webhook/wecom",
- "allow_from": []
- }
- }
-}
-```
-
-> WeCom Webhook 挂载在共享 Gateway 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。
-
-**快速设置 — 自建应用：**
-
-**1. 创建应用**
-
-* 企业微信管理后台 → 应用管理 → 创建应用
-* 复制 **AgentId** 和 **Secret**
-* 前往"我的企业"页面，复制 **CorpID**
-
-**2. 配置接收消息**
-
-* 在应用详情中，点击"接收消息" → "设置 API"
-* 设置 URL 为 `http://your-server:18790/webhook/wecom-app`
-* 生成 **Token** 和 **EncodingAESKey**
-
-**3. 配置**
-
-```json
-{
- "channels": {
- "wecom_app": {
- "enabled": true,
- "corp_id": "wwxxxxxxxxxxxxxxxx",
- "corp_secret": "YOUR_CORP_SECRET",
- "agent_id": 1000002,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
- "webhook_path": "/webhook/wecom-app",
- "allow_from": []
- }
- }
-}
-```
-
-**4. 运行**
-
-```bash
-picoclaw gateway
-```
-
-> **注意**: WeCom Webhook 回调挂载在 Gateway 端口（默认 18790）。使用反向代理配置 HTTPS。
-
-**快速设置 — 智能机器人 (AI Bot)：**
-
-**1. 创建 AI Bot**
-
-* 企业微信管理后台 → 应用管理 → AI Bot
-* 在 AI Bot 设置中配置回调 URL：`http://your-server:18790/webhook/wecom-aibot`
-* 复制 **Token** 并点击"随机生成" **EncodingAESKey**
-
-**2. 配置**
-
-```json
-{
- "channels": {
- "wecom_aibot": {
- "enabled": true,
- "token": "YOUR_TOKEN",
- "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
- "webhook_path": "/webhook/wecom-aibot",
+ "bot_id": "YOUR_BOT_ID",
+ "secret": "YOUR_SECRET",
+ "websocket_url": "wss://openws.work.weixin.qq.com",
+ "send_thinking_message": true,
"allow_from": [],
- "welcome_message": "你好！有什么可以帮你的？",
- "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+ "reasoning_channel_id": ""
}
}
}
@@ -599,7 +531,7 @@ picoclaw gateway
picoclaw gateway
```
-> **注意**: 企业微信 AI Bot 使用流式拉取协议，无回复超时问题。长任务（>30 秒）会自动切换到 `response_url` 推送投递。
+> 这个分支中旧的 `wecom_app` 和 `wecom_aibot` 配置已经被统一的 `channels.wecom` 替代。