diff --git a/docs/channels/wecom/README.fr.md b/docs/channels/wecom/README.fr.md
new file mode 100644
index 000000000..8f6cfe285
--- /dev/null
+++ b/docs/channels/wecom/README.fr.md
@@ -0,0 +1,148 @@
+> Retour au [README](../../../README.fr.md)
+
+# WeCom
+
+PicoClaw expose WeCom en tant que canal unique `channels.wecom`, basé sur l'API WebSocket officielle WeCom AI Bot.
+Ce canal remplace l'ancienne séparation `wecom`, `wecom_app` et `wecom_aibot` par un modèle de configuration unifié.
+
+> Aucune URL de callback webhook publique n'est requise. PicoClaw établit une connexion WebSocket sortante vers WeCom.
+
+## Fonctionnalités prises en charge
+
+- Chat privé et chat de groupe
+- Réponses en streaming côté canal via le protocole WeCom AI Bot
+- Messages entrants : texte, voix, image, fichier, vidéo et messages mixtes
+- Réponses sortantes : texte et médias (`image`, `file`, `voice`, `video`)
+- Onboarding par QR code via l'interface Web ou le CLI
+- Liste blanche partagée et routage `reasoning_channel_id`
+
+---
+
+## Démarrage rapide
+
+### Option 1 : Liaison QR via l'interface Web (recommandé)
+
+Ouvrez l'interface Web, accédez à **Channels → WeCom** et cliquez sur le bouton de liaison QR. Scannez le QR code avec WeCom et confirmez dans l'application — les identifiants sont enregistrés automatiquement.
+
+
+
+
+
+### Option 2 : Connexion QR via le CLI
+
+Exécutez :
+
+```bash
+picoclaw auth wecom
+```
+
+La commande :
+1. Demande un QR code à WeCom et l'affiche dans le terminal
+2. Affiche également un **lien QR code** que vous pouvez ouvrir dans un navigateur si le QR du terminal est difficile à scanner
+3. Attend la confirmation — après le scan, vous devez également **confirmer la connexion dans l'application WeCom**
+4. En cas de succès, écrit `bot_id` et `secret` dans `channels.wecom` et sauvegarde la configuration
+
+Le délai d'expiration par défaut est de **5 minutes**. Utilisez `--timeout` pour l'étendre :
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+> ⚠️ Scanner le QR code ne suffit pas — vous devez également appuyer sur **Confirmer** dans l'application WeCom, sinon la commande expirera.
+
+### Option 3 : Configuration manuelle
+
+Si vous disposez déjà d'un `bot_id` et d'un `secret` depuis la plateforme WeCom AI Bot, configurez directement :
+
+```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
+
+| Champ | Type | Défaut | Description |
+| ----- | ---- | ------ | ----------- |
+| `enabled` | bool | `false` | Activer le canal WeCom. |
+| `bot_id` | string | — | Identifiant WeCom AI Bot. Requis lorsque le canal est activé. |
+| `secret` | string | — | Secret WeCom AI Bot. Stocké chiffré dans `.security.yml`. Requis lorsque le canal est activé. |
+| `websocket_url` | string | `wss://openws.work.weixin.qq.com` | Point de terminaison WebSocket WeCom. |
+| `send_thinking_message` | bool | `true` | Envoyer un message `Processing...` avant le début de la réponse en streaming. |
+| `allow_from` | array | `[]` | Liste blanche des expéditeurs. Vide signifie autoriser tous les expéditeurs. |
+| `reasoning_channel_id` | string | `""` | ID de chat optionnel pour router la sortie de raisonnement vers une conversation séparée. |
+
+### Variables d'environnement
+
+Tous les champs peuvent être remplacés par des variables d'environnement avec le préfixe `PICOCLAW_CHANNELS_WECOM_` :
+
+| Variable d'environnement | Champ correspondant |
+| ------------------------ | ------------------- |
+| `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` |
+
+---
+
+## Comportement à l'exécution
+
+- PicoClaw maintient un tour WeCom actif pour que les réponses en streaming puissent continuer sur le même flux lorsque c'est possible.
+- Les réponses en streaming ont une durée maximale de **5,5 minutes** et un intervalle d'envoi minimum de **500 ms**.
+- Si le streaming n'est plus disponible, les réponses basculent vers la livraison par push actif.
+- Les associations de routes de chat expirent après **30 minutes** d'inactivité.
+- Les médias entrants sont téléchargés dans le stockage média local avant d'être transmis à l'agent.
+- Les médias sortants sont uploadés vers WeCom en tant que fichier temporaire, puis envoyés comme message média.
+- Les messages en double sont détectés et supprimés (tampon circulaire des 1000 derniers identifiants de messages).
+
+---
+
+## Migration depuis l'ancienne configuration WeCom
+
+| Configuration précédente | Migration |
+| ------------------------ | --------- |
+| `channels.wecom` (bot webhook) | Remplacer par `channels.wecom` avec `bot_id` + `secret`. |
+| `channels.wecom_app` | Supprimer. Utiliser `channels.wecom` à la place. |
+| `channels.wecom_aibot` | Déplacer `bot_id` et `secret` vers `channels.wecom`. |
+| `token`, `encoding_aes_key`, `webhook_url`, `webhook_path` | Plus utilisés. Supprimer de la configuration. |
+| `corp_id`, `corp_secret`, `agent_id` | Plus utilisés. Supprimer de la configuration. |
+| `welcome_message`, `processing_message`, `max_steps` | Ne font plus partie de la configuration du canal WeCom. |
+
+---
+
+## Dépannage
+
+### La liaison QR expire
+
+- Après avoir scanné le QR code, vous devez également **confirmer la connexion dans l'application WeCom**. Le scan seul ne suffit pas.
+- Relancez avec un `--timeout` plus long : `picoclaw auth wecom --timeout 10m`
+- Si le QR code dans le terminal est difficile à scanner, utilisez le **lien QR code** affiché en dessous pour l'ouvrir dans un navigateur.
+
+### QR code expiré
+
+- Le QR code a une durée de validité limitée. Relancez `picoclaw auth wecom` pour en obtenir un nouveau.
+
+### Échec de la connexion WebSocket
+
+- Vérifiez que `bot_id` et `secret` sont corrects.
+- Confirmez que l'hôte peut atteindre `wss://openws.work.weixin.qq.com` (WebSocket sortant, aucun port entrant nécessaire).
+
+### Les réponses n'arrivent pas
+
+- Vérifiez si `allow_from` bloque l'expéditeur.
+- Vérifiez que `channels.wecom.bot_id` et `channels.wecom.secret` sont définis et non vides.
diff --git a/docs/channels/wecom/README.ja.md b/docs/channels/wecom/README.ja.md
new file mode 100644
index 000000000..34b785ba5
--- /dev/null
+++ b/docs/channels/wecom/README.ja.md
@@ -0,0 +1,148 @@
+> [README](../../../README.ja.md) に戻る
+
+# WeCom
+
+PicoClaw は WeCom を公式 WeCom AI Bot WebSocket API に基づく単一の `channels.wecom` チャンネルとして公開します。
+従来の `wecom`、`wecom_app`、`wecom_aibot` の分割を統一された設定モデルに置き換えました。
+
+> パブリックな Webhook コールバック URL は不要です。PicoClaw は WeCom へのアウトバウンド WebSocket 接続を確立します。
+
+## サポートされる機能
+
+- ダイレクトチャットとグループチャット
+- WeCom AI Bot プロトコルによるチャンネル側ストリーミング返信
+- テキスト、音声、画像、ファイル、動画、ミックスメッセージの受信
+- テキストおよびメディア返信の送信（`image`、`file`、`voice`、`video`）
+- Web UI または CLI による QR コードオンボーディング
+- 共有許可リストと `reasoning_channel_id` ルーティング
+
+---
+
+## クイックスタート
+
+### オプション 1：Web UI QR バインディング（推奨）
+
+Web UI を開き、**Channels → WeCom** に移動して、QR バインディングボタンをクリックします。WeCom で QR コードをスキャンし、アプリ内で確認すると、認証情報が自動的に保存されます。
+
+
+
+
+
+### オプション 2：CLI QR ログイン
+
+実行：
+
+```bash
+picoclaw auth wecom
+```
+
+コマンドの動作：
+1. WeCom に QR コードをリクエストし、ターミナルに表示します
+2. ターミナルの QR コードがスキャンしにくい場合に備え、ブラウザで開ける **QR コードリンク** も表示します
+3. 確認をポーリングします — スキャン後、**WeCom アプリ内でログインを確認** する必要があります
+4. 成功すると、`bot_id` と `secret` を `channels.wecom` に書き込み、設定を保存します
+
+デフォルトのタイムアウトは **5 分** です。`--timeout` で延長できます：
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+> ⚠️ QR コードのスキャンだけでは不十分です — WeCom アプリ内で **確認** をタップする必要があります。そうしないとコマンドがタイムアウトします。
+
+### オプション 3：手動設定
+
+WeCom 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` | WeCom チャンネルを有効にする。 |
+| `bot_id` | string | — | WeCom AI Bot 識別子。有効時に必須。 |
+| `secret` | string | — | WeCom AI Bot シークレット。`.security.yml` に暗号化して保存。有効時に必須。 |
+| `websocket_url` | string | `wss://openws.work.weixin.qq.com` | WeCom WebSocket エンドポイント。 |
+| `send_thinking_message` | bool | `true` | ストリーミング返信の開始前に `Processing...` メッセージを送信する。 |
+| `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 はアクティブな WeCom ターンを維持し、可能な限り同じストリームでストリーミング返信を継続します。
+- ストリーミング返信の最大持続時間は **5.5 分**、最小送信間隔は **500ms** です。
+- ストリーミングが利用できなくなった場合、返信はアクティブプッシュ配信にフォールバックします。
+- チャットルートの関連付けは **30 分** の非アクティブ後に期限切れになります。
+- 受信メディアはエージェントに渡される前にローカルメディアストアにダウンロードされます。
+- 送信メディアは WeCom に一時ファイルとしてアップロードされ、メディアメッセージとして送信されます。
+- 重複メッセージは検出され抑制されます（最新 1000 件のメッセージ ID のリングバッファ）。
+
+---
+
+## レガシー WeCom 設定からの移行
+
+| 以前の設定 | 移行方法 |
+| ---------- | -------- |
+| `channels.wecom`（Webhook ボット） | `bot_id` + `secret` を使用する `channels.wecom` に置き換える。 |
+| `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` | WeCom チャンネル設定の一部ではなくなりました。 |
+
+---
+
+## トラブルシューティング
+
+### QR バインディングがタイムアウトする
+
+- QR コードをスキャンした後、**WeCom アプリ内でログインを確認** する必要があります。スキャンだけでは不十分です。
+- より長い `--timeout` で再実行してください：`picoclaw auth wecom --timeout 10m`
+- ターミナルの QR コードがスキャンしにくい場合は、その下に表示される **QR コードリンク** を使用してブラウザで開いてください。
+
+### QR コードの有効期限切れ
+
+- QR コードには有効期限があります。`picoclaw auth wecom` を再実行して新しいものを取得してください。
+
+### WebSocket 接続の失敗
+
+- `bot_id` と `secret` が正しいことを確認してください。
+- ホストが `wss://openws.work.weixin.qq.com` に到達できることを確認してください（アウトバウンド WebSocket、インバウンドポートは不要）。
+
+### 返信が届かない
+
+- `allow_from` が送信者をブロックしていないか確認してください。
+- `channels.wecom.bot_id` と `channels.wecom.secret` が設定されており、空でないことを確認してください。
diff --git a/docs/channels/wecom/README.pt-br.md b/docs/channels/wecom/README.pt-br.md
new file mode 100644
index 000000000..5d8cf10f0
--- /dev/null
+++ b/docs/channels/wecom/README.pt-br.md
@@ -0,0 +1,148 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# WeCom
+
+O PicoClaw expõe o WeCom como um único canal `channels.wecom`, construído sobre a API WebSocket oficial do WeCom AI Bot.
+Isso substitui a antiga separação `wecom`, `wecom_app` e `wecom_aibot` por um modelo de configuração unificado.
+
+> Nenhuma URL de callback webhook pública é necessária. O PicoClaw estabelece uma conexão WebSocket de saída para o WeCom.
+
+## Funcionalidades Suportadas
+
+- Chat direto e chat em grupo
+- Respostas em streaming pelo protocolo WeCom AI Bot
+- Mensagens recebidas: texto, voz, imagem, arquivo, vídeo e mensagens mistas
+- Respostas enviadas: texto e mídia (`image`, `file`, `voice`, `video`)
+- Onboarding por QR code via Web UI ou CLI
+- Lista de permissões compartilhada e roteamento `reasoning_channel_id`
+
+---
+
+## Início Rápido
+
+### Opção 1: Vinculação QR via Web UI (Recomendado)
+
+Abra a Web UI, navegue até **Channels → WeCom** e clique no botão de vinculação QR. Escaneie o QR code com o WeCom e confirme no aplicativo — as credenciais são salvas automaticamente.
+
+
+
+
+
+### Opção 2: Login QR via CLI
+
+Execute:
+
+```bash
+picoclaw auth wecom
+```
+
+O comando:
+1. Solicita um QR code ao WeCom e o exibe no terminal
+2. Também exibe um **Link do QR Code** que você pode abrir no navegador se o QR do terminal for difícil de escanear
+3. Aguarda a confirmação — após escanear, você também deve **confirmar o login dentro do aplicativo WeCom**
+4. Em caso de sucesso, grava `bot_id` e `secret` em `channels.wecom` e salva a configuração
+
+O timeout padrão é de **5 minutos**. Use `--timeout` para estendê-lo:
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+> ⚠️ Escanear o QR code não é suficiente — você também deve tocar em **Confirmar** dentro do aplicativo WeCom, caso contrário o comando expirará.
+
+### Opção 3: Configuração Manual
+
+Se você já possui um `bot_id` e `secret` da plataforma WeCom AI Bot, configure diretamente:
+
+```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": ""
+ }
+ }
+}
+```
+
+---
+
+## Configuração
+
+| Campo | Tipo | Padrão | Descrição |
+| ----- | ---- | ------ | --------- |
+| `enabled` | bool | `false` | Ativar o canal WeCom. |
+| `bot_id` | string | — | Identificador do WeCom AI Bot. Obrigatório quando ativado. |
+| `secret` | string | — | Secret do WeCom AI Bot. Armazenado criptografado em `.security.yml`. Obrigatório quando ativado. |
+| `websocket_url` | string | `wss://openws.work.weixin.qq.com` | Endpoint WebSocket do WeCom. |
+| `send_thinking_message` | bool | `true` | Enviar uma mensagem `Processing...` antes do início da resposta em streaming. |
+| `allow_from` | array | `[]` | Lista de permissões de remetentes. Vazio significa permitir todos os remetentes. |
+| `reasoning_channel_id` | string | `""` | ID de chat opcional para rotear a saída de raciocínio para uma conversa separada. |
+
+### Variáveis de Ambiente
+
+Todos os campos podem ser substituídos via variáveis de ambiente com o prefixo `PICOCLAW_CHANNELS_WECOM_`:
+
+| Variável de Ambiente | Campo Correspondente |
+| -------------------- | -------------------- |
+| `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` |
+
+---
+
+## Comportamento em Tempo de Execução
+
+- O PicoClaw mantém um turno WeCom ativo para que as respostas em streaming possam continuar no mesmo fluxo quando possível.
+- As respostas em streaming têm uma duração máxima de **5,5 minutos** e um intervalo mínimo de envio de **500ms**.
+- Se o streaming não estiver mais disponível, as respostas recorrem à entrega por push ativo.
+- As associações de rotas de chat expiram após **30 minutos** de inatividade.
+- A mídia recebida é baixada para o armazenamento de mídia local antes de ser passada ao agente.
+- A mídia enviada é carregada para o WeCom como um arquivo temporário e então enviada como uma mensagem de mídia.
+- Mensagens duplicadas são detectadas e suprimidas (buffer circular dos últimos 1000 IDs de mensagens).
+
+---
+
+## Migração da Configuração Legada do WeCom
+
+| Configuração anterior | Migração |
+| --------------------- | -------- |
+| `channels.wecom` (bot webhook) | Substituir por `channels.wecom` usando `bot_id` + `secret`. |
+| `channels.wecom_app` | Remover. Usar `channels.wecom` no lugar. |
+| `channels.wecom_aibot` | Mover `bot_id` e `secret` para `channels.wecom`. |
+| `token`, `encoding_aes_key`, `webhook_url`, `webhook_path` | Não mais utilizados. Remover da configuração. |
+| `corp_id`, `corp_secret`, `agent_id` | Não mais utilizados. Remover da configuração. |
+| `welcome_message`, `processing_message`, `max_steps` | Não fazem mais parte da configuração do canal WeCom. |
+
+---
+
+## Solução de Problemas
+
+### A vinculação QR expira
+
+- Após escanear o QR code, você também deve **confirmar o login dentro do aplicativo WeCom**. Escanear sozinho não é suficiente.
+- Execute novamente com um `--timeout` maior: `picoclaw auth wecom --timeout 10m`
+- Se o QR code no terminal for difícil de escanear, use o **Link do QR Code** exibido abaixo dele para abrir no navegador.
+
+### QR code expirado
+
+- O QR code tem validade limitada. Execute novamente `picoclaw auth wecom` para obter um novo.
+
+### Falha na conexão WebSocket
+
+- Verifique se `bot_id` e `secret` estão corretos.
+- Confirme que o host pode alcançar `wss://openws.work.weixin.qq.com` (WebSocket de saída, nenhuma porta de entrada necessária).
+
+### As respostas não chegam
+
+- Verifique se `allow_from` está bloqueando o remetente.
+- Verifique se `channels.wecom.bot_id` e `channels.wecom.secret` estão definidos e não vazios.
diff --git a/docs/channels/wecom/README.vi.md b/docs/channels/wecom/README.vi.md
new file mode 100644
index 000000000..caffb3465
--- /dev/null
+++ b/docs/channels/wecom/README.vi.md
@@ -0,0 +1,148 @@
+> Quay lại [README](../../../README.vi.md)
+
+# WeCom
+
+PicoClaw cung cấp WeCom dưới dạng một kênh duy nhất `channels.wecom`, được xây dựng trên API WebSocket chính thức của WeCom AI Bot.
+Điều này thay thế việc phân tách cũ `wecom`, `wecom_app` và `wecom_aibot` bằng một mô hình cấu hình thống nhất.
+
+> Không cần URL callback webhook công khai. PicoClaw thiết lập kết nối WebSocket đi ra tới WeCom.
+
+## Tính năng được hỗ trợ
+
+- Chat trực tiếp và chat nhóm
+- Phản hồi streaming qua giao thức WeCom AI Bot
+- Nhận tin nhắn văn bản, giọng nói, hình ảnh, tệp, video và tin nhắn hỗn hợp
+- Gửi phản hồi văn bản và phương tiện (`image`, `file`, `voice`, `video`)
+- Đăng ký qua mã QR bằng Web UI hoặc CLI
+- Danh sách cho phép chung và định tuyến `reasoning_channel_id`
+
+---
+
+## Bắt đầu nhanh
+
+### Tùy chọn 1: Liên kết QR qua Web UI (Khuyến nghị)
+
+Mở Web UI, điều hướng đến **Channels → WeCom** và nhấp vào nút liên kết QR. Quét mã QR bằng WeCom và xác nhận trong ứng dụng — thông tin đăng nhập được lưu tự động.
+
+
+
+
+
+### Tùy chọn 2: Đăng nhập QR qua CLI
+
+Chạy:
+
+```bash
+picoclaw auth wecom
+```
+
+Lệnh thực hiện:
+1. Yêu cầu mã QR từ WeCom và hiển thị trong terminal
+2. Đồng thời in ra một **Liên kết mã QR** mà bạn có thể mở trong trình duyệt nếu mã QR trên terminal khó quét
+3. Chờ xác nhận — sau khi quét, bạn cũng phải **xác nhận đăng nhập trong ứng dụng WeCom**
+4. Khi thành công, ghi `bot_id` và `secret` vào `channels.wecom` và lưu cấu hình
+
+Thời gian chờ mặc định là **5 phút**. Sử dụng `--timeout` để kéo dài:
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+> ⚠️ Quét mã QR là chưa đủ — bạn cũng phải nhấn **Xác nhận** trong ứng dụng WeCom, nếu không lệnh sẽ hết thời gian chờ.
+
+### Tùy chọn 3: Cấu hình thủ công
+
+Nếu bạn đã có `bot_id` và `secret` từ nền tảng WeCom AI Bot, hãy cấu hình trực tiếp:
+
+```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": ""
+ }
+ }
+}
+```
+
+---
+
+## Cấu hình
+
+| Trường | Kiểu | Mặc định | Mô tả |
+| ------ | ---- | -------- | ----- |
+| `enabled` | bool | `false` | Kích hoạt kênh WeCom. |
+| `bot_id` | string | — | Mã định danh WeCom AI Bot. Bắt buộc khi được kích hoạt. |
+| `secret` | string | — | Secret của WeCom AI Bot. Được lưu mã hóa trong `.security.yml`. Bắt buộc khi được kích hoạt. |
+| `websocket_url` | string | `wss://openws.work.weixin.qq.com` | Điểm cuối WebSocket của WeCom. |
+| `send_thinking_message` | bool | `true` | Gửi tin nhắn `Processing...` trước khi phản hồi streaming bắt đầu. |
+| `allow_from` | array | `[]` | Danh sách cho phép người gửi. Để trống nghĩa là cho phép tất cả. |
+| `reasoning_channel_id` | string | `""` | ID chat tùy chọn để định tuyến đầu ra suy luận đến một cuộc hội thoại riêng. |
+
+### Biến môi trường
+
+Tất cả các trường có thể được ghi đè bằng biến môi trường với tiền tố `PICOCLAW_CHANNELS_WECOM_`:
+
+| Biến môi trường | Trường tương ứng |
+| ---------------- | ---------------- |
+| `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` |
+
+---
+
+## Hành vi khi chạy
+
+- PicoClaw duy trì một lượt WeCom đang hoạt động để phản hồi streaming có thể tiếp tục trên cùng một luồng khi có thể.
+- Phản hồi streaming có thời lượng tối đa **5,5 phút** và khoảng cách gửi tối thiểu **500ms**.
+- Nếu streaming không còn khả dụng, phản hồi sẽ chuyển sang gửi push chủ động.
+- Các liên kết tuyến chat hết hạn sau **30 phút** không hoạt động.
+- Phương tiện nhận được sẽ được tải xuống bộ lưu trữ phương tiện cục bộ trước khi chuyển cho agent.
+- Phương tiện gửi đi được tải lên WeCom dưới dạng tệp tạm thời, sau đó gửi dưới dạng tin nhắn phương tiện.
+- Tin nhắn trùng lặp được phát hiện và loại bỏ (bộ đệm vòng của 1000 ID tin nhắn gần nhất).
+
+---
+
+## Di chuyển từ cấu hình WeCom cũ
+
+| Cấu hình trước đây | Di chuyển |
+| ------------------- | --------- |
+| `channels.wecom` (bot webhook) | Thay thế bằng `channels.wecom` sử dụng `bot_id` + `secret`. |
+| `channels.wecom_app` | Xóa. Sử dụng `channels.wecom` thay thế. |
+| `channels.wecom_aibot` | Di chuyển `bot_id` và `secret` sang `channels.wecom`. |
+| `token`, `encoding_aes_key`, `webhook_url`, `webhook_path` | Không còn sử dụng. Xóa khỏi cấu hình. |
+| `corp_id`, `corp_secret`, `agent_id` | Không còn sử dụng. Xóa khỏi cấu hình. |
+| `welcome_message`, `processing_message`, `max_steps` | Không còn là một phần của cấu hình kênh WeCom. |
+
+---
+
+## Khắc phục sự cố
+
+### Liên kết QR hết thời gian chờ
+
+- Sau khi quét mã QR, bạn cũng phải **xác nhận đăng nhập trong ứng dụng WeCom**. Chỉ quét là chưa đủ.
+- Chạy lại với `--timeout` lớn hơn: `picoclaw auth wecom --timeout 10m`
+- Nếu mã QR trên terminal khó quét, hãy sử dụng **Liên kết mã QR** được in bên dưới để mở trong trình duyệt.
+
+### Mã QR đã hết hạn
+
+- Mã QR có thời hạn hiệu lực giới hạn. Chạy lại `picoclaw auth wecom` để lấy mã mới.
+
+### Kết nối WebSocket thất bại
+
+- Kiểm tra xem `bot_id` và `secret` có chính xác không.
+- Xác nhận máy chủ có thể kết nối đến `wss://openws.work.weixin.qq.com` (WebSocket đi ra, không cần cổng đến).
+
+### Phản hồi không đến
+
+- Kiểm tra xem `allow_from` có đang chặn người gửi không.
+- Kiểm tra rằng `channels.wecom.bot_id` và `channels.wecom.secret` đã được thiết lập và không trống.