Merge upstream/main into feat/agent-sandbox

2026-02-20 22:55:53 +08:00 · 2026-02-20 22:55:53 +08:00 · 82e6c31928
commit 82e6c31928
parent e3dfe5f95c 1ef33c90ed
33 changed files with 6189 additions and 33 deletions
--- a/README.fr.md
+++ b/README.fr.md
@ -262,7 +262,7 @@ Et voilà ! Vous avez un assistant IA fonctionnel en 2 minutes.

 ## 💬 Applications de Chat

-Discutez avec votre PicoClaw via Telegram, Discord, DingTalk ou LINE
+Discutez avec votre PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom

 | Canal        | Configuration                          |
 | ------------ | -------------------------------------- |
@ -271,6 +271,7 @@ Discutez avec votre PicoClaw via Telegram, Discord, DingTalk ou LINE
 | **QQ**       | Facile (AppID + AppSecret)             |
 | **DingTalk** | Moyen (identifiants de l'application)  |
 | **LINE**     | Moyen (identifiants + URL de webhook)  |
+| **WeCom**    | Moyen (CorpID + configuration webhook) |

 <details>
 <summary><b>Telegram</b> (Recommandé)</summary>
@ -470,6 +471,87 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>WeCom (WeChat Work)</b></summary>
+
+PicoClaw prend en charge deux types d'intégration WeCom :
+
+**Option 1 : WeCom Bot (Robot Intelligent)** - Configuration plus facile, prend en charge les discussions de groupe
+**Option 2 : WeCom App (Application Personnalisée)** - Plus de fonctionnalités, messagerie proactive
+
+Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour des instructions détaillées.
+
+**Configuration Rapide - WeCom Bot :**
+
+**1. Créer un bot**
+
+* Accédez à la Console d'Administration WeCom → Discussion de Groupe → Ajouter un Bot de Groupe
+* Copiez l'URL du webhook (format : `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Configurer**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**Configuration Rapide - WeCom App :**
+
+**1. Créer une application**
+
+* Accédez à la Console d'Administration WeCom → Gestion des Applications → Créer une Application
+* Copiez l'**AgentId** et le **Secret**
+* Accédez à la page "Mon Entreprise", copiez le **CorpID**
+
+**2. Configurer la réception des messages**
+
+* Dans les détails de l'application, cliquez sur "Recevoir les Messages" → "Configurer l'API"
+* Définissez l'URL sur `http://your-server:18792/webhook/wecom-app`
+* Générez le **Token** et l'**EncodingAESKey**
+
+**3. Configurer**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+> **Note** : WeCom App nécessite l'ouverture du port 18792 pour les callbacks webhook. Utilisez un proxy inverse pour HTTPS en production.
+
+</details>
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Rejoignez le Réseau Social d'Agents

 Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
--- a/README.ja.md
+++ b/README.ja.md
@ -226,7 +226,7 @@ picoclaw agent -m "What is 2+2?"

 ## 💬 チャットアプリ

-Telegram、Discord、QQ、DingTalk、LINE で PicoClaw と会話できます
+Telegram、Discord、QQ、DingTalk、LINE、WeCom で PicoClaw と会話できます

 | チャネル | セットアップ |
 |---------|------------|
@ -235,6 +235,7 @@ Telegram、Discord、QQ、DingTalk、LINE で PicoClaw と会話できます
 | **QQ** | 簡単（AppID + AppSecret） |
 | **DingTalk** | 普通（アプリ認証情報） |
 | **LINE** | 普通（認証情報 + Webhook URL） |
+| **WeCom** | 普通（CorpID + Webhook設定） |

 <details>
 <summary><b>Telegram</b>（推奨）</summary>
@ -430,6 +431,87 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>WeCom (企業微信)</b></summary>
+
+PicoClaw は2種類の WeCom 統合をサポートしています：
+
+**オプション1: WeCom Bot (智能ロボット)** - 簡単な設定、グループチャット対応
+**オプション2: WeCom App (自作アプリ)** - より多機能、アクティブメッセージング対応
+
+詳細な設定手順は [WeCom App Configuration Guide](docs/wecom-app-configuration.md) を参照してください。
+
+**クイックセットアップ - WeCom Bot:**
+
+**1. ボットを作成**
+
+* WeCom 管理コンソール → グループチャット → グループボットを追加
+* Webhook URL をコピー（形式: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`）
+
+**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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**クイックセットアップ - WeCom App:**
+
+**1. アプリを作成**
+
+* WeCom 管理コンソール → アプリ管理 → アプリを作成
+* **AgentId** と **Secret** をコピー
+* "マイ会社" ページで **CorpID** をコピー
+
+**2. メッセージ受信を設定**
+
+* アプリ詳細で "メッセージを受信" → "APIを設定" をクリック
+* URL を `http://your-server:18792/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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. 起動**
+
+```bash
+picoclaw gateway
+```
+
+> **注意**: WeCom App は Webhook コールバック用にポート 18792 を開放する必要があります。本番環境では HTTPS 用のリバースプロキシを使用してください。
+
+</details>
+
 ## ⚙️ 設定

 設定ファイル: `~/.picoclaw/config.json`
--- a/README.md
+++ b/README.md
@ -264,7 +264,7 @@ That's it! You have a working AI assistant in 2 minutes.

 ## 💬 Chat Apps

-Talk to your picoclaw through Telegram, Discord, DingTalk, or LINE
+Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom

 | Channel      | Setup                              |
 | ------------ | ---------------------------------- |
@ -273,6 +273,7 @@ Talk to your picoclaw through Telegram, Discord, DingTalk, or LINE
 | **QQ**       | Easy (AppID + AppSecret)           |
 | **DingTalk** | Medium (app credentials)           |
 | **LINE**     | Medium (credentials + webhook URL) |
+| **WeCom**    | Medium (CorpID + webhook setup)    |

 <details>
 <summary><b>Telegram</b> (Recommended)</summary>
@ -334,7 +335,8 @@ picoclaw gateway
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
+      "allow_from": ["YOUR_USER_ID"],
+      "mention_only": false
    }
  }
 }
@ -347,6 +349,10 @@ picoclaw gateway
 * Bot Permissions: `Send Messages`, `Read Message History`
 * Open the generated invite URL and add the bot to your server

+**Optional: Mention-only mode**
+
+Set `"mention_only": true` to make the bot respond only when @-mentioned. Useful for shared servers where you want the bot to respond only when explicitly called.
+
 **6. Run**

 ```bash
@ -472,6 +478,87 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw supports two types of WeCom integration:
+
+**Option 1: WeCom Bot (智能机器人)** - Easier setup, supports group chats
+**Option 2: WeCom App (自建应用)** - More features, proactive messaging
+
+See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detailed setup instructions.
+
+**Quick Setup - WeCom Bot:**
+
+**1. Create a bot**
+
+* 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`)
+
+**2. Configure**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**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:18792/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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Run**
+
+```bash
+picoclaw gateway
+```
+
+> **Note**: WeCom App requires opening port 18792 for webhook callbacks. Use a reverse proxy for HTTPS.
+
+</details>
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network

 Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
--- a/README.pt-br.md
+++ b/README.pt-br.md
@ -263,7 +263,7 @@ Pronto! Você tem um assistente de IA funcionando em 2 minutos.

 ## 💬 Integração com Apps de Chat

-Converse com seu PicoClaw via Telegram, Discord, DingTalk ou LINE.
+Converse com seu PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom.

 | Canal | Nível de Configuração |
 | --- | --- |
@ -272,6 +272,7 @@ Converse com seu PicoClaw via Telegram, Discord, DingTalk ou LINE.
 | **QQ** | Fácil (AppID + AppSecret) |
 | **DingTalk** | Médio (credenciais do app) |
 | **LINE** | Médio (credenciais + webhook URL) |
+| **WeCom** | Médio (CorpID + configuração webhook) |

 <details>
 <summary><b>Telegram</b> (Recomendado)</summary>
@ -471,6 +472,87 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>WeCom (WeChat Work)</b></summary>
+
+O PicoClaw suporta dois tipos de integração WeCom:
+
+**Opção 1: WeCom Bot (Robô Inteligente)** - Configuração mais fácil, suporta chats em grupo
+**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas
+
+Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para instruções detalhadas.
+
+**Configuração Rápida - WeCom Bot:**
+
+**1. Criar um bot**
+
+* Acesse o Console de Administração WeCom → Chat em Grupo → Adicionar Bot de Grupo
+* Copie a URL do webhook (formato: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Configurar**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**Configuração Rápida - WeCom App:**
+
+**1. Criar um aplicativo**
+
+* Acesse o Console de Administração WeCom → Gerenciamento de Aplicativos → Criar Aplicativo
+* Copie o **AgentId** e o **Secret**
+* Acesse a página "Minha Empresa", copie o **CorpID**
+
+**2. Configurar recebimento de mensagens**
+
+* Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API"
+* Defina a URL como `http://your-server:18792/webhook/wecom-app`
+* Gere o **Token** e o **EncodingAESKey**
+
+**3. Configurar**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: O WeCom App requer a abertura da porta 18792 para callbacks de webhook. Use um proxy reverso para HTTPS em produção.
+
+</details>
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Junte-se a Rede Social de Agentes

 Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado.
--- a/README.vi.md
+++ b/README.vi.md
@ -243,7 +243,7 @@ Vậy là xong! Bạn đã có một trợ lý AI hoạt động chỉ trong 2 p

 ## 💬 Tích hợp ứng dụng Chat

-Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk hoặc LINE.
+Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk, LINE hoặc WeCom.

 | Kênh | Mức độ thiết lập |
 | --- | --- |
@ -252,6 +252,7 @@ Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk hoặc LINE.
 | **QQ** | Dễ (AppID + AppSecret) |
 | **DingTalk** | Trung bình (app credentials) |
 | **LINE** | Trung bình (credentials + webhook URL) |
+| **WeCom** | Trung bình (CorpID + cấu hình webhook) |

 <details>
 <summary><b>Telegram</b> (Khuyên dùng)</summary>
@ -451,6 +452,87 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>WeCom (WeChat Work)</b></summary>
+
+PicoClaw hỗ trợ hai loại tích hợp WeCom:
+
+**Tùy chọn 1: WeCom Bot (Robot Thông minh)** - Thiết lập dễ dàng hơn, hỗ trợ chat nhóm
+**Tùy chọn 2: WeCom App (Ứng dụng Tự xây dựng)** - Nhiều tính năng hơn, nhắn tin chủ động
+
+Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) để biết hướng dẫn chi tiết.
+
+**Thiết lập Nhanh - WeCom Bot:**
+
+**1. Tạo bot**
+
+* Truy cập Bảng điều khiển Quản trị WeCom → Chat Nhóm → Thêm Bot Nhóm
+* Sao chép URL webhook (định dạng: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Cấu hình**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**Thiết lập Nhanh - WeCom App:**
+
+**1. Tạo ứng dụng**
+
+* Truy cập Bảng điều khiển Quản trị WeCom → Quản lý Ứng dụng → Tạo Ứng dụng
+* Sao chép **AgentId** và **Secret**
+* Truy cập trang "Công ty của tôi", sao chép **CorpID**
+
+**2. Cấu hình nhận tin nhắn**
+
+* Trong chi tiết ứng dụng, nhấp vào "Nhận Tin nhắn" → "Thiết lập API"
+* Đặt URL thành `http://your-server:18792/webhook/wecom-app`
+* Tạo **Token** và **EncodingAESKey**
+
+**3. Cấu hình**
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> **Lưu ý**: WeCom App yêu cầu mở cổng 18792 cho callback webhook. Sử dụng proxy ngược cho HTTPS trong môi trường sản xuất.
+
+</details>
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Tham gia Mạng xã hội Agent

 Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn qua CLI hoặc bất kỳ ứng dụng Chat nào đã tích hợp.
--- a/README.zh.md
+++ b/README.zh.md
@ -273,14 +273,15 @@ picoclaw agent -m "2+2 等于几？"

 ## 💬 聊天应用集成 (Chat Apps)

-通过 Telegram, Discord 或钉钉与您的 PicoClaw 对话。
+通过 Telegram, Discord, 钉钉或企业微信与您的 PicoClaw 对话。

 | 渠道 | 设置难度 |
 | --- | --- |
 | **Telegram** | 简单 (仅需 token) |
 | **Discord** | 简单 (bot token + intents) |
 | **QQ** | 简单 (AppID + AppSecret) |
-| **钉钉 (DingTalk)** | 中等 (app credentials) |
+| **钉钉 (DingTalk)** | 中等 (应用凭证) |
+| **企业微信 (WeCom)** | 中等 (企业ID + Webhook配置) |

 <details>
 <summary><b>Telegram</b> (推荐)</summary>
@ -438,6 +439,88 @@ picoclaw gateway

 </details>

+<details>
+<summary><b>企业微信 (WeCom)</b></summary>
+
+PicoClaw 支持两种企业微信集成方式：
+
+**选项1: 智能机器人 (WeCom Bot)** - 设置更简单，支持群聊
+**选项2: 自建应用 (WeCom App)** - 功能更丰富，支持主动推送消息
+
+详见 [企业微信自建应用配置指南](docs/wecom-app-configuration.md)。
+
+**快速设置 - 智能机器人：**
+
+**1. 创建机器人**
+
+* 前往企业微信管理后台 → 群聊 → 添加群机器人
+* 复制 Webhook URL (格式: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**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_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**快速设置 - 自建应用：**
+
+**1. 创建应用**
+
+* 前往企业微信管理后台 → 应用管理 → 创建应用
+* 复制 **AgentId** 和 **Secret**
+* 前往"我的企业"页面，复制 **CorpID**
+
+**2. 配置接收消息**
+
+* 在应用详情页，点击"接收消息" → "设置API"
+* 设置 URL 为 `http://your-server:18792/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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. 运行**
+
+```bash
+picoclaw gateway
+
+```
+
+> **注意**: 自建应用需要开放 18792 端口用于接收 Webhook 回调。生产环境建议使用反向代理配置 HTTPS。
+
+</details>
+
 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络

 只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
--- a/cmd/picoclaw/cmd_skills.go
+++ b/cmd/picoclaw/cmd_skills.go
@ -11,7 +11,9 @@ import (
 	"strings"
 	"time"

+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )

 func skillsHelp() {
@ -30,6 +32,7 @@ func skillsHelp() {
 	fmt.Println("  picoclaw skills install-builtin")
 	fmt.Println("  picoclaw skills list-builtin")
 	fmt.Println("  picoclaw skills remove weather")
+	fmt.Println("  picoclaw skills install --registry clawhub github")
 }

 func skillsListCmd(loader *skills.SkillsLoader) {
@ -50,13 +53,27 @@ func skillsListCmd(loader *skills.SkillsLoader) {
 	}
 }

-func skillsInstallCmd(installer *skills.SkillInstaller) {
+func skillsInstallCmd(installer *skills.SkillInstaller, cfg *config.Config) {
 	if len(os.Args) < 4 {
 		fmt.Println("Usage: picoclaw skills install <github-repo>")
-		fmt.Println("Example: picoclaw skills install sipeed/picoclaw-skills/weather")
+		fmt.Println("       picoclaw skills install --registry <name> <slug>")
 		return
 	}

+	// Check for --registry flag.
+	if os.Args[3] == "--registry" {
+		if len(os.Args) < 6 {
+			fmt.Println("Usage: picoclaw skills install --registry <name> <slug>")
+			fmt.Println("Example: picoclaw skills install --registry clawhub github")
+			return
+		}
+		registryName := os.Args[4]
+		slug := os.Args[5]
+		skillsInstallFromRegistry(cfg, registryName, slug)
+		return
+	}
+
+	// Default: install from GitHub (backward compatible).
 	repo := os.Args[3]
 	fmt.Printf("Installing skill from %s...\n", repo)

@ -64,11 +81,83 @@ func skillsInstallCmd(installer *skills.SkillInstaller) {
 	defer cancel()

 	if err := installer.InstallFromGitHub(ctx, repo); err != nil {
-		fmt.Printf("✗ Failed to install skill: %v\n", err)
+		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
 		os.Exit(1)
 	}

-	fmt.Printf("✓ Skill '%s' installed successfully!\n", filepath.Base(repo))
+	fmt.Printf("\u2713 Skill '%s' installed successfully!\n", filepath.Base(repo))
+}
+
+// skillsInstallFromRegistry installs a skill from a named registry (e.g. clawhub).
+func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) {
+	err := utils.ValidateSkillIdentifier(registryName)
+	if err != nil {
+		fmt.Printf("\u2717 Invalid registry name: %v\n", err)
+		os.Exit(1)
+	}
+
+	err = utils.ValidateSkillIdentifier(slug)
+	if err != nil {
+		fmt.Printf("\u2717 Invalid slug: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Installing skill '%s' from %s registry...\n", slug, registryName)
+
+	registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+		MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+		ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+	})
+
+	registry := registryMgr.GetRegistry(registryName)
+	if registry == nil {
+		fmt.Printf("\u2717 Registry '%s' not found or not enabled. Check your config.json.\n", registryName)
+		os.Exit(1)
+	}
+
+	workspace := cfg.WorkspacePath()
+	targetDir := filepath.Join(workspace, "skills", slug)
+
+	if _, err := os.Stat(targetDir); err == nil {
+		fmt.Printf("\u2717 Skill '%s' already installed at %s\n", slug, targetDir)
+		os.Exit(1)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	if err := os.MkdirAll(filepath.Join(workspace, "skills"), 0755); err != nil {
+		fmt.Printf("\u2717 Failed to create skills directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	result, err := registry.DownloadAndInstall(ctx, slug, "", targetDir)
+	if err != nil {
+		rmErr := os.RemoveAll(targetDir)
+		if rmErr != nil {
+			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
+		}
+		fmt.Printf("\u2717 Failed to install skill: %v\n", err)
+		os.Exit(1)
+	}
+
+	if result.IsMalwareBlocked {
+		rmErr := os.RemoveAll(targetDir)
+		if rmErr != nil {
+			fmt.Printf("\u2717 Failed to remove partial install: %v\n", rmErr)
+		}
+		fmt.Printf("\u2717 Skill '%s' is flagged as malicious and cannot be installed.\n", slug)
+		os.Exit(1)
+	}
+
+	if result.IsSuspicious {
+		fmt.Printf("\u26a0\ufe0f  Warning: skill '%s' is flagged as suspicious.\n", slug)
+	}
+
+	fmt.Printf("\u2713 Skill '%s' v%s installed successfully!\n", slug, result.Version)
+	if result.Summary != "" {
+		fmt.Printf("  %s\n", result.Summary)
+	}
 }

 func skillsRemoveCmd(installer *skills.SkillInstaller, skillName string) {
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@ -141,7 +141,7 @@ func main() {
 		case "list":
 			skillsListCmd(skillsLoader)
 		case "install":
-			skillsInstallCmd(installer)
+			skillsInstallCmd(installer, cfg)
 		case "remove", "uninstall":
 			if len(os.Args) < 4 {
 				fmt.Println("Usage: picoclaw skills remove <skill-name>")
--- a/config/config.example.json
+++ b/config/config.example.json
@ -57,6 +57,13 @@
    "discord": {
      "enabled": false,
      "token": "YOUR_DISCORD_BOT_TOKEN",
+      "allow_from": [],
+      "mention_only": false
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "YOUR_QQ_APP_ID",
+      "app_secret": "YOUR_QQ_APP_SECRET",
      "allow_from": []
    },
    "maixcam": {
@ -106,6 +113,32 @@
      "reconnect_interval": 5,
      "group_trigger_prefix": [],
      "allow_from": []
+    },
+    "wecom": {
+      "_comment": "WeCom Bot (智能机器人) - Easier setup, supports group chats",
+      "enabled": false,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18793,
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    },
+    "wecom_app": {
+      "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only. See docs/wecom-app-configuration.md",
+      "enabled": false,
+      "corp_id": "YOUR_CORP_ID",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
    }
  },
  "providers": {
@ -172,6 +205,10 @@
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
      "perplexity": {
        "enabled": false,
        "api_key": "pplx-xxx",
@ -180,6 +217,21 @@
    },
    "cron": {
      "exec_timeout_minutes": 5
+    },
+    "exec": {
+      "enable_deny_patterns": false,
+      "custom_deny_patterns": []
+    },
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "search_path": "/api/v1/search",
+          "skills_path": "/api/v1/skills",
+          "download_path": "/api/v1/download"
+        }
+      }
    }
  },
  "heartbeat": {
--- a/docs/wecom-app-configuration.md
+++ b/docs/wecom-app-configuration.md
@ -0,0 +1,117 @@
+# 企业微信自建应用 (WeCom App) 配置指南
+
+本文档介绍如何在 PicoClaw 中配置企业微信自建应用 (wecom-app) 通道。
+
+## 功能特性
+
+| 功能 | 支持状态 |
+|------|---------|
+| 被动接收消息 | ✅ |
+| 主动发送消息 | ✅ |
+| 私聊 | ✅ |
+| 群聊 | ❌ |
+
+## 配置步骤
+
+### 1. 企业微信后台配置
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → 选择自建应用
+3. 记录以下信息：
+   - **AgentId**: 应用详情页显示
+   - **Secret**: 点击"查看"获取
+4. 进入"我的企业"页面，记录 **企业ID** (CorpID)
+
+### 2. 接收消息配置
+
+1. 在应用详情页，点击"接收消息"的"设置API接收"
+2. 填写以下信息：
+   - **URL**: `http://your-server:18792/webhook/wecom-app`
+   - **Token**: 随机生成或自定义（用于签名验证）
+   - **EncodingAESKey**: 点击"随机生成"生成43字符的密钥
+3. 点击"保存"时，企业微信会发送验证请求
+
+### 3. PicoClaw 配置
+
+在 `config.json` 中添加以下配置：
+
+```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_host": "0.0.0.0",
+      "webhook_port": 18792,
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+## 常见问题
+
+### 1. 回调URL验证失败
+
+**症状**: 企业微信保存API接收消息时提示验证失败
+
+**检查项**:
+- 确认服务器防火墙已开放 18792 端口
+- 确认 `corp_id`、`token`、`encoding_aes_key` 配置正确
+- 查看 PicoClaw 日志是否有请求到达
+
+### 2. 中文消息解密失败
+
+**症状**: 发送中文消息时出现 `invalid padding size` 错误
+
+**原因**: 企业微信使用非标准的 PKCS7 填充（32字节块大小）
+
+**解决**: 确保使用最新版本的 PicoClaw，已修复此问题。
+
+### 3. 端口冲突
+
+**症状**: 启动时提示端口已被占用
+
+**解决**: 修改 `webhook_port` 为其他端口，如 18794
+
+## 技术细节
+
+### 加密算法
+
+- **算法**: AES-256-CBC
+- **密钥**: EncodingAESKey Base64解码后的32字节
+- **IV**: AESKey的前16字节
+- **填充**: PKCS7（块大小为32字节，非标准16字节）
+- **消息格式**: XML
+
+### 消息结构
+
+解密后的消息格式：
+```
+random(16B) + msg_len(4B) + msg + receiveid
+```
+
+其中 `receiveid` 对于自建应用是 `corp_id`。
+
+## 调试
+
+启用调试模式查看详细日志：
+
+```bash
+picoclaw gateway --debug
+```
+
+关键日志标识：
+- `wecom_app`: WeCom App 通道相关日志
+- `wecom_common`: 加密解密相关日志
+
+## 参考文档
+
+- [企业微信官方文档 - 接收消息](https://developer.work.weixin.qq.com/document/path/96211)
+- [企业微信官方加解密库](https://github.com/sbzhu/weworkapi_golang)
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@ -24,6 +24,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/routing"
+	"github.com/sipeed/picoclaw/pkg/skills"
 	"github.com/sipeed/picoclaw/pkg/state"
 	"github.com/sipeed/picoclaw/pkg/tools"
 	"github.com/sipeed/picoclaw/pkg/utils"
@ -118,6 +119,15 @@ func registerSharedTools(cfg *config.Config, msgBus *bus.MessageBus, registry *A
 		})
 		agent.Tools.Register(messageTool)

+		// Skill discovery and installation tools
+		registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+			MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+			ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+		})
+		searchCache := skills.NewSearchCache(cfg.Tools.Skills.SearchCache.MaxSize, time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second)
+		agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache))
+		agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace))
+
 		// Spawn tool with allowlist checker
 		subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace, msgBus)
 		subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
--- a/pkg/channels/discord.go
+++ b/pkg/channels/discord.go
@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"strings"
 	"sync"
 	"time"

@ -28,6 +29,7 @@ type DiscordChannel struct {
 	ctx         context.Context
 	typingMu    sync.Mutex
 	typingStop  map[string]chan struct{} // chatID → stop signal
+	botUserID   string                   // stored for mention checking
 }

 func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
@ -63,6 +65,14 @@ func (c *DiscordChannel) Start(ctx context.Context) error {
 	logger.InfoC("discord", "Starting Discord bot")

 	c.ctx = ctx
+
+	// Get bot user ID before opening session to avoid race condition
+	botUser, err := c.session.User("@me")
+	if err != nil {
+		return fmt.Errorf("failed to get bot user: %w", err)
+	}
+	c.botUserID = botUser.ID
+
 	c.session.AddHandler(c.handleMessage)

 	if err := c.session.Open(); err != nil {
@ -71,10 +81,6 @@ func (c *DiscordChannel) Start(ctx context.Context) error {

 	c.setRunning(true)

-	botUser, err := c.session.User("@me")
-	if err != nil {
-		return fmt.Errorf("failed to get bot user: %w", err)
-	}
 	logger.InfoCF("discord", "Discord bot connected", map[string]any{
 		"username": botUser.Username,
 		"user_id":  botUser.ID,
@ -131,7 +137,7 @@ func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) erro
 }

 func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content string) error {
-	// 使用传入的 ctx 进行超时控制
+	// Use the passed ctx for timeout control
 	sendCtx, cancel := context.WithTimeout(ctx, sendTimeout)
 	defer cancel()

@ -152,7 +158,7 @@ func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content strin
 	}
 }

-// appendContent 安全地追加内容到现有文本
+// appendContent safely appends content to existing text
 func appendContent(content, suffix string) string {
 	if content == "" {
 		return suffix
@ -169,7 +175,7 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		return
 	}

-	// 检查白名单，避免为被拒绝的用户下载附件和转录
+	// Check allowlist first to avoid downloading attachments and transcribing for rejected users
 	if !c.IsAllowed(m.Author.ID) {
 		logger.DebugCF("discord", "Message rejected by allowlist", map[string]any{
 			"user_id": m.Author.ID,
@ -177,6 +183,24 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		return
 	}

+	// If configured to only respond to mentions, check if bot is mentioned
+	// Skip this check for DMs (GuildID is empty) - DMs should always be responded to
+	if c.config.MentionOnly && m.GuildID != "" {
+		isMentioned := false
+		for _, mention := range m.Mentions {
+			if mention.ID == c.botUserID {
+				isMentioned = true
+				break
+			}
+		}
+		if !isMentioned {
+			logger.DebugCF("discord", "Message ignored - bot not mentioned", map[string]any{
+				"user_id": m.Author.ID,
+			})
+			return
+		}
+	}
+
 	senderID := m.Author.ID
 	senderName := m.Author.Username
 	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
@ -184,10 +208,11 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 	}

 	content := m.Content
+	content = c.stripBotMention(content)
 	mediaPaths := make([]string, 0, len(m.Attachments))
 	localFiles := make([]string, 0, len(m.Attachments))

-	// 确保临时文件在函数返回时被清理
+	// Ensure temp files are cleaned up when function returns
 	defer func() {
 		for _, file := range localFiles {
 			if err := os.Remove(file); err != nil {
@ -211,7 +236,7 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 				if c.transcriber != nil && c.transcriber.IsAvailable() {
 					ctx, cancel := context.WithTimeout(c.getContext(), transcriptionTimeout)
 					result, err := c.transcriber.Transcribe(ctx, localPath)
-					cancel() // 立即释放context资源，避免在for循环中泄漏
+					cancel() // Release context resources immediately to avoid leaks in for loop

 					if err != nil {
 						logger.ErrorCF("discord", "Voice transcription failed", map[string]any{
@ -333,3 +358,15 @@ func (c *DiscordChannel) downloadAttachment(url, filename string) string {
 		LoggerPrefix: "discord",
 	})
 }
+
+// stripBotMention removes the bot mention from the message content.
+// Discord mentions have the format <@USER_ID> or <@!USER_ID> (with nickname).
+func (c *DiscordChannel) stripBotMention(text string) string {
+	if c.botUserID == "" {
+		return text
+	}
+	// Remove both regular mention <@USER_ID> and nickname mention <@!USER_ID>
+	text = strings.ReplaceAll(text, fmt.Sprintf("<@%s>", c.botUserID), "")
+	text = strings.ReplaceAll(text, fmt.Sprintf("<@!%s>", c.botUserID), "")
+	return strings.TrimSpace(text)
+}
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@ -176,6 +176,32 @@ func (m *Manager) initChannels() error {
 		}
 	}

+	if m.config.Channels.WeCom.Enabled && m.config.Channels.WeCom.Token != "" {
+		logger.DebugC("channels", "Attempting to initialize WeCom channel")
+		wecom, err := NewWeComBotChannel(m.config.Channels.WeCom, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize WeCom channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["wecom"] = wecom
+			logger.InfoC("channels", "WeCom channel enabled successfully")
+		}
+	}
+
+	if m.config.Channels.WeComApp.Enabled && m.config.Channels.WeComApp.CorpID != "" {
+		logger.DebugC("channels", "Attempting to initialize WeCom App channel")
+		wecomApp, err := NewWeComAppChannel(m.config.Channels.WeComApp, m.bus)
+		if err != nil {
+			logger.ErrorCF("channels", "Failed to initialize WeCom App channel", map[string]interface{}{
+				"error": err.Error(),
+			})
+		} else {
+			m.channels["wecom_app"] = wecomApp
+			logger.InfoC("channels", "WeCom App channel enabled successfully")
+		}
+	}
+
 	logger.InfoCF("channels", "Channel initialization completed", map[string]interface{}{
 		"enabled_channels": len(m.channels),
 	})
--- a/pkg/channels/wecom.go
+++ b/pkg/channels/wecom.go
@ -0,0 +1,604 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// WeCom Bot (企业微信智能机器人) channel implementation
+// Uses webhook callback mode for receiving messages and webhook API for sending replies
+
+package channels
+
+import (
+	"bytes"
+	"context"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/sha1"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+// WeComBotChannel implements the Channel interface for WeCom Bot (企业微信智能机器人)
+// Uses webhook callback mode - simpler than WeCom App but only supports passive replies
+type WeComBotChannel struct {
+	*BaseChannel
+	config        config.WeComConfig
+	server        *http.Server
+	ctx           context.Context
+	cancel        context.CancelFunc
+	processedMsgs map[string]bool // Message deduplication: msg_id -> processed
+	msgMu         sync.RWMutex
+}
+
+// WeComBotMessage represents the JSON message structure from WeCom Bot (AIBOT)
+type WeComBotMessage struct {
+	MsgID    string `json:"msgid"`
+	AIBotID  string `json:"aibotid"`
+	ChatID   string `json:"chatid"`   // Session ID, only present for group chats
+	ChatType string `json:"chattype"` // "single" for DM, "group" for group chat
+	From     struct {
+		UserID string `json:"userid"`
+	} `json:"from"`
+	ResponseURL string `json:"response_url"`
+	MsgType     string `json:"msgtype"` // text, image, voice, file, mixed
+	Text        struct {
+		Content string `json:"content"`
+	} `json:"text"`
+	Image struct {
+		URL string `json:"url"`
+	} `json:"image"`
+	Voice struct {
+		Content string `json:"content"` // Voice to text content
+	} `json:"voice"`
+	File struct {
+		URL string `json:"url"`
+	} `json:"file"`
+	Mixed struct {
+		MsgItem []struct {
+			MsgType string `json:"msgtype"`
+			Text    struct {
+				Content string `json:"content"`
+			} `json:"text"`
+			Image struct {
+				URL string `json:"url"`
+			} `json:"image"`
+		} `json:"msg_item"`
+	} `json:"mixed"`
+	Quote struct {
+		MsgType string `json:"msgtype"`
+		Text    struct {
+			Content string `json:"content"`
+		} `json:"text"`
+	} `json:"quote"`
+}
+
+// WeComBotReplyMessage represents the reply message structure
+type WeComBotReplyMessage struct {
+	MsgType string `json:"msgtype"`
+	Text    struct {
+		Content string `json:"content"`
+	} `json:"text,omitempty"`
+}
+
+// NewWeComBotChannel creates a new WeCom Bot channel instance
+func NewWeComBotChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*WeComBotChannel, error) {
+	if cfg.Token == "" || cfg.WebhookURL == "" {
+		return nil, fmt.Errorf("wecom token and webhook_url are required")
+	}
+
+	base := NewBaseChannel("wecom", cfg, messageBus, cfg.AllowFrom)
+
+	return &WeComBotChannel{
+		BaseChannel:   base,
+		config:        cfg,
+		processedMsgs: make(map[string]bool),
+	}, nil
+}
+
+// Name returns the channel name
+func (c *WeComBotChannel) Name() string {
+	return "wecom"
+}
+
+// Start initializes the WeCom Bot channel with HTTP webhook server
+func (c *WeComBotChannel) Start(ctx context.Context) error {
+	logger.InfoC("wecom", "Starting WeCom Bot channel...")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	// Setup HTTP server for webhook
+	mux := http.NewServeMux()
+	webhookPath := c.config.WebhookPath
+	if webhookPath == "" {
+		webhookPath = "/webhook/wecom"
+	}
+	mux.HandleFunc(webhookPath, c.handleWebhook)
+
+	// Health check endpoint
+	mux.HandleFunc("/health/wecom", c.handleHealth)
+
+	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
+	c.server = &http.Server{
+		Addr:    addr,
+		Handler: mux,
+	}
+
+	c.setRunning(true)
+	logger.InfoCF("wecom", "WeCom Bot channel started", map[string]interface{}{
+		"address": addr,
+		"path":    webhookPath,
+	})
+
+	// Start server in goroutine
+	go func() {
+		if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.ErrorCF("wecom", "HTTP server error", map[string]interface{}{
+				"error": err.Error(),
+			})
+		}
+	}()
+
+	return nil
+}
+
+// Stop gracefully stops the WeCom Bot channel
+func (c *WeComBotChannel) Stop(ctx context.Context) error {
+	logger.InfoC("wecom", "Stopping WeCom Bot channel...")
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	if c.server != nil {
+		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		defer cancel()
+		c.server.Shutdown(shutdownCtx)
+	}
+
+	c.setRunning(false)
+	logger.InfoC("wecom", "WeCom Bot channel stopped")
+	return nil
+}
+
+// Send sends a message to WeCom user via webhook API
+// Note: WeCom Bot can only reply within the configured timeout (default 5 seconds) of receiving a message
+// For delayed responses, we use the webhook URL
+func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("wecom channel not running")
+	}
+
+	logger.DebugCF("wecom", "Sending message via webhook", map[string]interface{}{
+		"chat_id": msg.ChatID,
+		"preview": utils.Truncate(msg.Content, 100),
+	})
+
+	return c.sendWebhookReply(ctx, msg.ChatID, msg.Content)
+}
+
+// handleWebhook handles incoming webhook requests from WeCom
+func (c *WeComBotChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	if r.Method == http.MethodGet {
+		// Handle verification request
+		c.handleVerification(ctx, w, r)
+		return
+	}
+
+	if r.Method == http.MethodPost {
+		// Handle message callback
+		c.handleMessageCallback(ctx, w, r)
+		return
+	}
+
+	http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+}
+
+// handleVerification handles the URL verification request from WeCom
+func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+	msgSignature := query.Get("msg_signature")
+	timestamp := query.Get("timestamp")
+	nonce := query.Get("nonce")
+	echostr := query.Get("echostr")
+
+	if msgSignature == "" || timestamp == "" || nonce == "" || echostr == "" {
+		http.Error(w, "Missing parameters", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature
+	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+		logger.WarnC("wecom", "Signature verification failed")
+		http.Error(w, "Invalid signature", http.StatusForbidden)
+		return
+	}
+
+	// Decrypt echostr
+	// For AIBOT (智能机器人), receiveid should be empty string ""
+	// Reference: https://developer.work.weixin.qq.com/document/path/101033
+	decryptedEchoStr, err := WeComDecryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
+	if err != nil {
+		logger.ErrorCF("wecom", "Failed to decrypt echostr", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	// Remove BOM and whitespace as per WeCom documentation
+	// The response must be plain text without quotes, BOM, or newlines
+	decryptedEchoStr = strings.TrimSpace(decryptedEchoStr)
+	decryptedEchoStr = strings.TrimPrefix(decryptedEchoStr, "\xef\xbb\xbf") // Remove UTF-8 BOM
+	w.Write([]byte(decryptedEchoStr))
+}
+
+// handleMessageCallback handles incoming messages from WeCom
+func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+	msgSignature := query.Get("msg_signature")
+	timestamp := query.Get("timestamp")
+	nonce := query.Get("nonce")
+
+	if msgSignature == "" || timestamp == "" || nonce == "" {
+		http.Error(w, "Missing parameters", http.StatusBadRequest)
+		return
+	}
+
+	// Read request body
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Failed to read body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	// Parse XML to get encrypted message
+	var encryptedMsg struct {
+		XMLName    xml.Name `xml:"xml"`
+		ToUserName string   `xml:"ToUserName"`
+		Encrypt    string   `xml:"Encrypt"`
+		AgentID    string   `xml:"AgentID"`
+	}
+
+	if err := xml.Unmarshal(body, &encryptedMsg); err != nil {
+		logger.ErrorCF("wecom", "Failed to parse XML", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Invalid XML", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature
+	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+		logger.WarnC("wecom", "Message signature verification failed")
+		http.Error(w, "Invalid signature", http.StatusForbidden)
+		return
+	}
+
+	// Decrypt message
+	// For AIBOT (智能机器人), receiveid should be empty string ""
+	// Reference: https://developer.work.weixin.qq.com/document/path/101033
+	decryptedMsg, err := WeComDecryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
+	if err != nil {
+		logger.ErrorCF("wecom", "Failed to decrypt message", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	// Parse decrypted JSON message (AIBOT uses JSON format)
+	var msg WeComBotMessage
+	if err := json.Unmarshal([]byte(decryptedMsg), &msg); err != nil {
+		logger.ErrorCF("wecom", "Failed to parse decrypted message", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Invalid message format", http.StatusBadRequest)
+		return
+	}
+
+	// Process the message asynchronously with context
+	go c.processMessage(ctx, msg)
+
+	// Return success response immediately
+	// WeCom Bot requires response within configured timeout (default 5 seconds)
+	w.Write([]byte("success"))
+}
+
+// processMessage processes the received message
+func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessage) {
+	// Skip unsupported message types
+	if msg.MsgType != "text" && msg.MsgType != "image" && msg.MsgType != "voice" && msg.MsgType != "file" && msg.MsgType != "mixed" {
+		logger.DebugCF("wecom", "Skipping non-supported message type", map[string]interface{}{
+			"msg_type": msg.MsgType,
+		})
+		return
+	}
+
+	// Message deduplication: Use msg_id to prevent duplicate processing
+	msgID := msg.MsgID
+	c.msgMu.Lock()
+	if c.processedMsgs[msgID] {
+		c.msgMu.Unlock()
+		logger.DebugCF("wecom", "Skipping duplicate message", map[string]interface{}{
+			"msg_id": msgID,
+		})
+		return
+	}
+	c.processedMsgs[msgID] = true
+	c.msgMu.Unlock()
+
+	// Clean up old messages periodically (keep last 1000)
+	if len(c.processedMsgs) > 1000 {
+		c.msgMu.Lock()
+		c.processedMsgs = make(map[string]bool)
+		c.msgMu.Unlock()
+	}
+
+	senderID := msg.From.UserID
+
+	// Determine if this is a group chat or direct message
+	// ChatType: "single" for DM, "group" for group chat
+	isGroupChat := msg.ChatType == "group"
+
+	var chatID, peerKind, peerID string
+	if isGroupChat {
+		// Group chat: use ChatID as chatID and peer_id
+		chatID = msg.ChatID
+		peerKind = "group"
+		peerID = msg.ChatID
+	} else {
+		// Direct message: use senderID as chatID and peer_id
+		chatID = senderID
+		peerKind = "direct"
+		peerID = senderID
+	}
+
+	// Extract content based on message type
+	var content string
+	switch msg.MsgType {
+	case "text":
+		content = msg.Text.Content
+	case "voice":
+		content = msg.Voice.Content // Voice to text content
+	case "mixed":
+		// For mixed messages, concatenate text items
+		for _, item := range msg.Mixed.MsgItem {
+			if item.MsgType == "text" {
+				content += item.Text.Content
+			}
+		}
+	case "image", "file":
+		// For image and file, we don't have text content
+		content = ""
+	}
+
+	// Build metadata
+	metadata := map[string]string{
+		"msg_type":     msg.MsgType,
+		"msg_id":       msg.MsgID,
+		"platform":     "wecom",
+		"peer_kind":    peerKind,
+		"peer_id":      peerID,
+		"response_url": msg.ResponseURL,
+	}
+	if isGroupChat {
+		metadata["chat_id"] = msg.ChatID
+		metadata["sender_id"] = senderID
+	}
+
+	logger.DebugCF("wecom", "Received message", map[string]interface{}{
+		"sender_id":     senderID,
+		"msg_type":      msg.MsgType,
+		"peer_kind":     peerKind,
+		"is_group_chat": isGroupChat,
+		"preview":       utils.Truncate(content, 50),
+	})
+
+	// Handle the message through the base channel
+	c.HandleMessage(senderID, chatID, content, nil, metadata)
+}
+
+// sendWebhookReply sends a reply using the webhook URL
+func (c *WeComBotChannel) sendWebhookReply(ctx context.Context, userID, content string) error {
+	reply := WeComBotReplyMessage{
+		MsgType: "text",
+	}
+	reply.Text.Content = content
+
+	jsonData, err := json.Marshal(reply)
+	if err != nil {
+		return fmt.Errorf("failed to marshal reply: %w", err)
+	}
+
+	// Use configurable timeout (default 5 seconds)
+	timeout := c.config.ReplyTimeout
+	if timeout <= 0 {
+		timeout = 5
+	}
+
+	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.config.WebhookURL, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("failed to send webhook reply: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	// Check response
+	var result struct {
+		ErrCode int    `json:"errcode"`
+		ErrMsg  string `json:"errmsg"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if result.ErrCode != 0 {
+		return fmt.Errorf("webhook API error: %s (code: %d)", result.ErrMsg, result.ErrCode)
+	}
+
+	return nil
+}
+
+// handleHealth handles health check requests
+func (c *WeComBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
+	status := map[string]interface{}{
+		"status":  "ok",
+		"running": c.IsRunning(),
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(status)
+}
+
+// WeCom common utilities for both WeCom Bot and WeCom App
+// The following functions were moved from wecom_common.go
+
+// WeComVerifySignature verifies the message signature for WeCom
+// This is a common function used by both WeCom Bot and WeCom App
+func WeComVerifySignature(token, msgSignature, timestamp, nonce, msgEncrypt string) bool {
+	if token == "" {
+		return true // Skip verification if token is not set
+	}
+
+	// Sort parameters
+	params := []string{token, timestamp, nonce, msgEncrypt}
+	sort.Strings(params)
+
+	// Concatenate
+	str := strings.Join(params, "")
+
+	// SHA1 hash
+	hash := sha1.Sum([]byte(str))
+	expectedSignature := fmt.Sprintf("%x", hash)
+
+	return expectedSignature == msgSignature
+}
+
+// WeComDecryptMessage decrypts the encrypted message using AES
+// This is a common function used by both WeCom Bot and WeCom App
+// For AIBOT, receiveid should be the aibotid; for other apps, it should be corp_id
+func WeComDecryptMessage(encryptedMsg, encodingAESKey string) (string, error) {
+	return WeComDecryptMessageWithVerify(encryptedMsg, encodingAESKey, "")
+}
+
+// WeComDecryptMessageWithVerify decrypts the encrypted message and optionally verifies receiveid
+// receiveid: for AIBOT use aibotid, for WeCom App use corp_id. If empty, skip verification.
+func WeComDecryptMessageWithVerify(encryptedMsg, encodingAESKey, receiveid string) (string, error) {
+	if encodingAESKey == "" {
+		// No encryption, return as is (base64 decode)
+		decoded, err := base64.StdEncoding.DecodeString(encryptedMsg)
+		if err != nil {
+			return "", err
+		}
+		return string(decoded), nil
+	}
+
+	// Decode AES key (base64)
+	aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
+	if err != nil {
+		return "", fmt.Errorf("failed to decode AES key: %w", err)
+	}
+
+	// Decode encrypted message
+	cipherText, err := base64.StdEncoding.DecodeString(encryptedMsg)
+	if err != nil {
+		return "", fmt.Errorf("failed to decode message: %w", err)
+	}
+
+	// AES decrypt
+	block, err := aes.NewCipher(aesKey)
+	if err != nil {
+		return "", fmt.Errorf("failed to create cipher: %w", err)
+	}
+
+	if len(cipherText) < aes.BlockSize {
+		return "", fmt.Errorf("ciphertext too short")
+	}
+
+	// IV is the first 16 bytes of AESKey
+	iv := aesKey[:aes.BlockSize]
+	mode := cipher.NewCBCDecrypter(block, iv)
+	plainText := make([]byte, len(cipherText))
+	mode.CryptBlocks(plainText, cipherText)
+
+	// Remove PKCS7 padding
+	plainText, err = pkcs7UnpadWeCom(plainText)
+	if err != nil {
+		return "", fmt.Errorf("failed to unpad: %w", err)
+	}
+
+	// Parse message structure
+	// Format: random(16) + msg_len(4) + msg + receiveid
+	if len(plainText) < 20 {
+		return "", fmt.Errorf("decrypted message too short")
+	}
+
+	msgLen := binary.BigEndian.Uint32(plainText[16:20])
+	if int(msgLen) > len(plainText)-20 {
+		return "", fmt.Errorf("invalid message length")
+	}
+
+	msg := plainText[20 : 20+msgLen]
+
+	// Verify receiveid if provided
+	if receiveid != "" && len(plainText) > 20+int(msgLen) {
+		actualReceiveID := string(plainText[20+msgLen:])
+		if actualReceiveID != receiveid {
+			return "", fmt.Errorf("receiveid mismatch: expected %s, got %s", receiveid, actualReceiveID)
+		}
+	}
+
+	return string(msg), nil
+}
+
+// pkcs7UnpadWeCom removes PKCS7 padding with validation
+// WeCom uses block size of 32 (not standard AES block size of 16)
+const wecomBlockSize = 32
+
+func pkcs7UnpadWeCom(data []byte) ([]byte, error) {
+	if len(data) == 0 {
+		return data, nil
+	}
+	padding := int(data[len(data)-1])
+	// WeCom uses 32-byte block size for PKCS7 padding
+	if padding == 0 || padding > wecomBlockSize {
+		return nil, fmt.Errorf("invalid padding size: %d", padding)
+	}
+	if padding > len(data) {
+		return nil, fmt.Errorf("padding size larger than data")
+	}
+	// Verify all padding bytes
+	for i := 0; i < padding; i++ {
+		if data[len(data)-1-i] != byte(padding) {
+			return nil, fmt.Errorf("invalid padding byte at position %d", i)
+		}
+	}
+	return data[:len(data)-padding], nil
+}
--- a/pkg/channels/wecom_app.go
+++ b/pkg/channels/wecom_app.go
@ -0,0 +1,639 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// WeCom App (企业微信自建应用) channel implementation
+// Supports receiving messages via webhook callback and sending messages proactively
+
+package channels
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+const (
+	wecomAPIBase = "https://qyapi.weixin.qq.com"
+)
+
+// WeComAppChannel implements the Channel interface for WeCom App (企业微信自建应用)
+type WeComAppChannel struct {
+	*BaseChannel
+	config        config.WeComAppConfig
+	server        *http.Server
+	accessToken   string
+	tokenExpiry   time.Time
+	tokenMu       sync.RWMutex
+	ctx           context.Context
+	cancel        context.CancelFunc
+	processedMsgs map[string]bool // Message deduplication: msg_id -> processed
+	msgMu         sync.RWMutex
+}
+
+// WeComXMLMessage represents the XML message structure from WeCom
+type WeComXMLMessage struct {
+	XMLName      xml.Name `xml:"xml"`
+	ToUserName   string   `xml:"ToUserName"`
+	FromUserName string   `xml:"FromUserName"`
+	CreateTime   int64    `xml:"CreateTime"`
+	MsgType      string   `xml:"MsgType"`
+	Content      string   `xml:"Content"`
+	MsgId        int64    `xml:"MsgId"`
+	AgentID      int64    `xml:"AgentID"`
+	PicUrl       string   `xml:"PicUrl"`
+	MediaId      string   `xml:"MediaId"`
+	Format       string   `xml:"Format"`
+	ThumbMediaId string   `xml:"ThumbMediaId"`
+	LocationX    float64  `xml:"Location_X"`
+	LocationY    float64  `xml:"Location_Y"`
+	Scale        int      `xml:"Scale"`
+	Label        string   `xml:"Label"`
+	Title        string   `xml:"Title"`
+	Description  string   `xml:"Description"`
+	Url          string   `xml:"Url"`
+	Event        string   `xml:"Event"`
+	EventKey     string   `xml:"EventKey"`
+}
+
+// WeComTextMessage represents text message for sending
+type WeComTextMessage struct {
+	ToUser  string `json:"touser"`
+	MsgType string `json:"msgtype"`
+	AgentID int64  `json:"agentid"`
+	Text    struct {
+		Content string `json:"content"`
+	} `json:"text"`
+	Safe int `json:"safe,omitempty"`
+}
+
+// WeComMarkdownMessage represents markdown message for sending
+type WeComMarkdownMessage struct {
+	ToUser   string `json:"touser"`
+	MsgType  string `json:"msgtype"`
+	AgentID  int64  `json:"agentid"`
+	Markdown struct {
+		Content string `json:"content"`
+	} `json:"markdown"`
+}
+
+// WeComImageMessage represents image message for sending
+type WeComImageMessage struct {
+	ToUser  string `json:"touser"`
+	MsgType string `json:"msgtype"`
+	AgentID int64  `json:"agentid"`
+	Image   struct {
+		MediaID string `json:"media_id"`
+	} `json:"image"`
+}
+
+// WeComAccessTokenResponse represents the access token API response
+type WeComAccessTokenResponse struct {
+	ErrCode     int    `json:"errcode"`
+	ErrMsg      string `json:"errmsg"`
+	AccessToken string `json:"access_token"`
+	ExpiresIn   int    `json:"expires_in"`
+}
+
+// WeComSendMessageResponse represents the send message API response
+type WeComSendMessageResponse struct {
+	ErrCode      int    `json:"errcode"`
+	ErrMsg       string `json:"errmsg"`
+	InvalidUser  string `json:"invaliduser"`
+	InvalidParty string `json:"invalidparty"`
+	InvalidTag   string `json:"invalidtag"`
+}
+
+// PKCS7Padding adds PKCS7 padding
+type PKCS7Padding struct{}
+
+// NewWeComAppChannel creates a new WeCom App channel instance
+func NewWeComAppChannel(cfg config.WeComAppConfig, messageBus *bus.MessageBus) (*WeComAppChannel, error) {
+	if cfg.CorpID == "" || cfg.CorpSecret == "" || cfg.AgentID == 0 {
+		return nil, fmt.Errorf("wecom_app corp_id, corp_secret and agent_id are required")
+	}
+
+	base := NewBaseChannel("wecom_app", cfg, messageBus, cfg.AllowFrom)
+
+	return &WeComAppChannel{
+		BaseChannel:   base,
+		config:        cfg,
+		processedMsgs: make(map[string]bool),
+	}, nil
+}
+
+// Name returns the channel name
+func (c *WeComAppChannel) Name() string {
+	return "wecom_app"
+}
+
+// Start initializes the WeCom App channel with HTTP webhook server
+func (c *WeComAppChannel) Start(ctx context.Context) error {
+	logger.InfoC("wecom_app", "Starting WeCom App channel...")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	// Get initial access token
+	if err := c.refreshAccessToken(); err != nil {
+		logger.WarnCF("wecom_app", "Failed to get initial access token", map[string]interface{}{
+			"error": err.Error(),
+		})
+	}
+
+	// Start token refresh goroutine
+	go c.tokenRefreshLoop()
+
+	// Setup HTTP server for webhook
+	mux := http.NewServeMux()
+	webhookPath := c.config.WebhookPath
+	if webhookPath == "" {
+		webhookPath = "/webhook/wecom-app"
+	}
+	mux.HandleFunc(webhookPath, c.handleWebhook)
+
+	// Health check endpoint
+	mux.HandleFunc("/health/wecom-app", c.handleHealth)
+
+	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
+	c.server = &http.Server{
+		Addr:    addr,
+		Handler: mux,
+	}
+
+	c.setRunning(true)
+	logger.InfoCF("wecom_app", "WeCom App channel started", map[string]interface{}{
+		"address": addr,
+		"path":    webhookPath,
+	})
+
+	// Start server in goroutine
+	go func() {
+		if err := c.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.ErrorCF("wecom_app", "HTTP server error", map[string]interface{}{
+				"error": err.Error(),
+			})
+		}
+	}()
+
+	return nil
+}
+
+// Stop gracefully stops the WeCom App channel
+func (c *WeComAppChannel) Stop(ctx context.Context) error {
+	logger.InfoC("wecom_app", "Stopping WeCom App channel...")
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	if c.server != nil {
+		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		defer cancel()
+		c.server.Shutdown(shutdownCtx)
+	}
+
+	c.setRunning(false)
+	logger.InfoC("wecom_app", "WeCom App channel stopped")
+	return nil
+}
+
+// Send sends a message to WeCom user proactively using access token
+func (c *WeComAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return fmt.Errorf("wecom_app channel not running")
+	}
+
+	accessToken := c.getAccessToken()
+	if accessToken == "" {
+		return fmt.Errorf("no valid access token available")
+	}
+
+	logger.DebugCF("wecom_app", "Sending message", map[string]interface{}{
+		"chat_id": msg.ChatID,
+		"preview": utils.Truncate(msg.Content, 100),
+	})
+
+	return c.sendTextMessage(ctx, accessToken, msg.ChatID, msg.Content)
+}
+
+// handleWebhook handles incoming webhook requests from WeCom
+func (c *WeComAppChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
+	// Log all incoming requests for debugging
+	logger.DebugCF("wecom_app", "Received webhook request", map[string]interface{}{
+		"method": r.Method,
+		"url":    r.URL.String(),
+		"path":   r.URL.Path,
+		"query":  r.URL.RawQuery,
+	})
+
+	if r.Method == http.MethodGet {
+		// Handle verification request
+		c.handleVerification(ctx, w, r)
+		return
+	}
+
+	if r.Method == http.MethodPost {
+		// Handle message callback
+		c.handleMessageCallback(ctx, w, r)
+		return
+	}
+
+	logger.WarnCF("wecom_app", "Method not allowed", map[string]interface{}{
+		"method": r.Method,
+	})
+	http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+}
+
+// handleVerification handles the URL verification request from WeCom
+func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+	msgSignature := query.Get("msg_signature")
+	timestamp := query.Get("timestamp")
+	nonce := query.Get("nonce")
+	echostr := query.Get("echostr")
+
+	logger.DebugCF("wecom_app", "Handling verification request", map[string]interface{}{
+		"msg_signature": msgSignature,
+		"timestamp":     timestamp,
+		"nonce":         nonce,
+		"echostr":       echostr,
+		"corp_id":       c.config.CorpID,
+	})
+
+	if msgSignature == "" || timestamp == "" || nonce == "" || echostr == "" {
+		logger.ErrorC("wecom_app", "Missing parameters in verification request")
+		http.Error(w, "Missing parameters", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature
+	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
+		logger.WarnCF("wecom_app", "Signature verification failed", map[string]interface{}{
+			"token":         c.config.Token,
+			"msg_signature": msgSignature,
+			"timestamp":     timestamp,
+			"nonce":         nonce,
+		})
+		http.Error(w, "Invalid signature", http.StatusForbidden)
+		return
+	}
+
+	logger.DebugC("wecom_app", "Signature verification passed")
+
+	// Decrypt echostr with CorpID verification
+	// For WeCom App (自建应用), receiveid should be corp_id
+	logger.DebugCF("wecom_app", "Attempting to decrypt echostr", map[string]interface{}{
+		"encoding_aes_key": c.config.EncodingAESKey,
+		"corp_id":          c.config.CorpID,
+	})
+	decryptedEchoStr, err := WeComDecryptMessageWithVerify(echostr, c.config.EncodingAESKey, c.config.CorpID)
+	if err != nil {
+		logger.ErrorCF("wecom_app", "Failed to decrypt echostr", map[string]interface{}{
+			"error":            err.Error(),
+			"encoding_aes_key": c.config.EncodingAESKey,
+			"corp_id":          c.config.CorpID,
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	logger.DebugCF("wecom_app", "Successfully decrypted echostr", map[string]interface{}{
+		"decrypted": decryptedEchoStr,
+	})
+
+	// Remove BOM and whitespace as per WeCom documentation
+	// The response must be plain text without quotes, BOM, or newlines
+	decryptedEchoStr = strings.TrimSpace(decryptedEchoStr)
+	decryptedEchoStr = strings.TrimPrefix(decryptedEchoStr, "\xef\xbb\xbf") // Remove UTF-8 BOM
+	w.Write([]byte(decryptedEchoStr))
+}
+
+// handleMessageCallback handles incoming messages from WeCom
+func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query()
+	msgSignature := query.Get("msg_signature")
+	timestamp := query.Get("timestamp")
+	nonce := query.Get("nonce")
+
+	if msgSignature == "" || timestamp == "" || nonce == "" {
+		http.Error(w, "Missing parameters", http.StatusBadRequest)
+		return
+	}
+
+	// Read request body
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Failed to read body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	// Parse XML to get encrypted message
+	var encryptedMsg struct {
+		XMLName    xml.Name `xml:"xml"`
+		ToUserName string   `xml:"ToUserName"`
+		Encrypt    string   `xml:"Encrypt"`
+		AgentID    string   `xml:"AgentID"`
+	}
+
+	if err := xml.Unmarshal(body, &encryptedMsg); err != nil {
+		logger.ErrorCF("wecom_app", "Failed to parse XML", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Invalid XML", http.StatusBadRequest)
+		return
+	}
+
+	// Verify signature
+	if !WeComVerifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
+		logger.WarnC("wecom_app", "Message signature verification failed")
+		http.Error(w, "Invalid signature", http.StatusForbidden)
+		return
+	}
+
+	// Decrypt message with CorpID verification
+	// For WeCom App (自建应用), receiveid should be corp_id
+	decryptedMsg, err := WeComDecryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, c.config.CorpID)
+	if err != nil {
+		logger.ErrorCF("wecom_app", "Failed to decrypt message", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Decryption failed", http.StatusInternalServerError)
+		return
+	}
+
+	// Parse decrypted XML message
+	var msg WeComXMLMessage
+	if err := xml.Unmarshal([]byte(decryptedMsg), &msg); err != nil {
+		logger.ErrorCF("wecom_app", "Failed to parse decrypted message", map[string]interface{}{
+			"error": err.Error(),
+		})
+		http.Error(w, "Invalid message format", http.StatusBadRequest)
+		return
+	}
+
+	// Process the message with context
+	go c.processMessage(ctx, msg)
+
+	// Return success response immediately
+	// WeCom App requires response within configured timeout (default 5 seconds)
+	w.Write([]byte("success"))
+}
+
+// processMessage processes the received message
+func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessage) {
+	// Skip non-text messages for now (can be extended)
+	if msg.MsgType != "text" && msg.MsgType != "image" && msg.MsgType != "voice" {
+		logger.DebugCF("wecom_app", "Skipping non-supported message type", map[string]interface{}{
+			"msg_type": msg.MsgType,
+		})
+		return
+	}
+
+	// Message deduplication: Use msg_id to prevent duplicate processing
+	// As per WeCom documentation, use msg_id for deduplication
+	msgID := fmt.Sprintf("%d", msg.MsgId)
+	c.msgMu.Lock()
+	if c.processedMsgs[msgID] {
+		c.msgMu.Unlock()
+		logger.DebugCF("wecom_app", "Skipping duplicate message", map[string]interface{}{
+			"msg_id": msgID,
+		})
+		return
+	}
+	c.processedMsgs[msgID] = true
+	c.msgMu.Unlock()
+
+	// Clean up old messages periodically (keep last 1000)
+	if len(c.processedMsgs) > 1000 {
+		c.msgMu.Lock()
+		c.processedMsgs = make(map[string]bool)
+		c.msgMu.Unlock()
+	}
+
+	senderID := msg.FromUserName
+	chatID := senderID // WeCom App uses user ID as chat ID for direct messages
+
+	// Build metadata
+	// WeCom App only supports direct messages (private chat)
+	metadata := map[string]string{
+		"msg_type":    msg.MsgType,
+		"msg_id":      fmt.Sprintf("%d", msg.MsgId),
+		"agent_id":    fmt.Sprintf("%d", msg.AgentID),
+		"platform":    "wecom_app",
+		"media_id":    msg.MediaId,
+		"create_time": fmt.Sprintf("%d", msg.CreateTime),
+		"peer_kind":   "direct",
+		"peer_id":     senderID,
+	}
+
+	content := msg.Content
+
+	logger.DebugCF("wecom_app", "Received message", map[string]interface{}{
+		"sender_id": senderID,
+		"msg_type":  msg.MsgType,
+		"preview":   utils.Truncate(content, 50),
+	})
+
+	// Handle the message through the base channel
+	c.HandleMessage(senderID, chatID, content, nil, metadata)
+}
+
+// tokenRefreshLoop periodically refreshes the access token
+func (c *WeComAppChannel) tokenRefreshLoop() {
+	ticker := time.NewTicker(5 * time.Minute)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		case <-ticker.C:
+			if err := c.refreshAccessToken(); err != nil {
+				logger.ErrorCF("wecom_app", "Failed to refresh access token", map[string]interface{}{
+					"error": err.Error(),
+				})
+			}
+		}
+	}
+}
+
+// refreshAccessToken gets a new access token from WeCom API
+func (c *WeComAppChannel) refreshAccessToken() error {
+	apiURL := fmt.Sprintf("%s/cgi-bin/gettoken?corpid=%s&corpsecret=%s",
+		wecomAPIBase, url.QueryEscape(c.config.CorpID), url.QueryEscape(c.config.CorpSecret))
+
+	resp, err := http.Get(apiURL)
+	if err != nil {
+		return fmt.Errorf("failed to request access token: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var tokenResp WeComAccessTokenResponse
+	if err := json.Unmarshal(body, &tokenResp); err != nil {
+		return fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if tokenResp.ErrCode != 0 {
+		return fmt.Errorf("API error: %s (code: %d)", tokenResp.ErrMsg, tokenResp.ErrCode)
+	}
+
+	c.tokenMu.Lock()
+	c.accessToken = tokenResp.AccessToken
+	c.tokenExpiry = time.Now().Add(time.Duration(tokenResp.ExpiresIn-300) * time.Second) // Refresh 5 minutes early
+	c.tokenMu.Unlock()
+
+	logger.DebugC("wecom_app", "Access token refreshed successfully")
+	return nil
+}
+
+// getAccessToken returns the current valid access token
+func (c *WeComAppChannel) getAccessToken() string {
+	c.tokenMu.RLock()
+	defer c.tokenMu.RUnlock()
+
+	if time.Now().After(c.tokenExpiry) {
+		return ""
+	}
+
+	return c.accessToken
+}
+
+// sendTextMessage sends a text message to a user
+func (c *WeComAppChannel) sendTextMessage(ctx context.Context, accessToken, userID, content string) error {
+	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
+
+	msg := WeComTextMessage{
+		ToUser:  userID,
+		MsgType: "text",
+		AgentID: c.config.AgentID,
+	}
+	msg.Text.Content = content
+
+	jsonData, err := json.Marshal(msg)
+	if err != nil {
+		return fmt.Errorf("failed to marshal message: %w", err)
+	}
+
+	// Use configurable timeout (default 5 seconds)
+	timeout := c.config.ReplyTimeout
+	if timeout <= 0 {
+		timeout = 5
+	}
+
+	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("failed to send message: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var sendResp WeComSendMessageResponse
+	if err := json.Unmarshal(body, &sendResp); err != nil {
+		return fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if sendResp.ErrCode != 0 {
+		return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
+	}
+
+	return nil
+}
+
+// sendMarkdownMessage sends a markdown message to a user
+func (c *WeComAppChannel) sendMarkdownMessage(ctx context.Context, accessToken, userID, content string) error {
+	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
+
+	msg := WeComMarkdownMessage{
+		ToUser:  userID,
+		MsgType: "markdown",
+		AgentID: c.config.AgentID,
+	}
+	msg.Markdown.Content = content
+
+	jsonData, err := json.Marshal(msg)
+	if err != nil {
+		return fmt.Errorf("failed to marshal message: %w", err)
+	}
+
+	// Use configurable timeout (default 5 seconds)
+	timeout := c.config.ReplyTimeout
+	if timeout <= 0 {
+		timeout = 5
+	}
+
+	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{Timeout: time.Duration(timeout) * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("failed to send message: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response: %w", err)
+	}
+
+	var sendResp WeComSendMessageResponse
+	if err := json.Unmarshal(body, &sendResp); err != nil {
+		return fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if sendResp.ErrCode != 0 {
+		return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
+	}
+
+	return nil
+}
+
+// handleHealth handles health check requests
+func (c *WeComAppChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
+	status := map[string]interface{}{
+		"status":    "ok",
+		"running":   c.IsRunning(),
+		"has_token": c.getAccessToken() != "",
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(status)
+}
--- a/pkg/channels/wecom_app_test.go
+++ b/pkg/channels/wecom_app_test.go
--- a/pkg/channels/wecom_test.go
+++ b/pkg/channels/wecom_test.go
@ -0,0 +1,755 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// WeCom Bot (企业微信智能机器人) channel tests
+
+package channels
+
+import (
+	"bytes"
+	"context"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/sha1"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"encoding/xml"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// generateTestAESKey generates a valid test AES key
+func generateTestAESKey() string {
+	// AES key needs to be 32 bytes (256 bits) for AES-256
+	key := make([]byte, 32)
+	for i := range key {
+		key[i] = byte(i)
+	}
+	// Return base64 encoded key without padding
+	return base64.StdEncoding.EncodeToString(key)[:43]
+}
+
+// encryptTestMessage encrypts a message for testing (AIBOT JSON format)
+func encryptTestMessage(message, aesKey string) (string, error) {
+	// Decode AES key
+	key, err := base64.StdEncoding.DecodeString(aesKey + "=")
+	if err != nil {
+		return "", err
+	}
+
+	// Prepare message: random(16) + msg_len(4) + msg + receiveid
+	random := make([]byte, 0, 16)
+	for i := 0; i < 16; i++ {
+		random = append(random, byte(i))
+	}
+
+	msgBytes := []byte(message)
+	receiveID := []byte("test_aibot_id")
+
+	msgLen := uint32(len(msgBytes))
+	lenBytes := make([]byte, 4)
+	binary.BigEndian.PutUint32(lenBytes, msgLen)
+
+	plainText := append(random, lenBytes...)
+	plainText = append(plainText, msgBytes...)
+	plainText = append(plainText, receiveID...)
+
+	// PKCS7 padding
+	blockSize := aes.BlockSize
+	padding := blockSize - len(plainText)%blockSize
+	padText := bytes.Repeat([]byte{byte(padding)}, padding)
+	plainText = append(plainText, padText...)
+
+	// Encrypt
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", err
+	}
+
+	mode := cipher.NewCBCEncrypter(block, key[:aes.BlockSize])
+	cipherText := make([]byte, len(plainText))
+	mode.CryptBlocks(cipherText, plainText)
+
+	return base64.StdEncoding.EncodeToString(cipherText), nil
+}
+
+// generateSignature generates a signature for testing
+func generateSignature(token, timestamp, nonce, msgEncrypt string) string {
+	params := []string{token, timestamp, nonce, msgEncrypt}
+	sort.Strings(params)
+	str := strings.Join(params, "")
+	hash := sha1.Sum([]byte(str))
+	return fmt.Sprintf("%x", hash)
+}
+
+func TestNewWeComBotChannel(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+
+	t.Run("missing token", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:      "",
+			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+		}
+		_, err := NewWeComBotChannel(cfg, msgBus)
+		if err == nil {
+			t.Error("expected error for missing token, got nil")
+		}
+	})
+
+	t.Run("missing webhook_url", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:      "test_token",
+			WebhookURL: "",
+		}
+		_, err := NewWeComBotChannel(cfg, msgBus)
+		if err == nil {
+			t.Error("expected error for missing webhook_url, got nil")
+		}
+	})
+
+	t.Run("valid config", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:      "test_token",
+			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			AllowFrom:  []string{"user1", "user2"},
+		}
+		ch, err := NewWeComBotChannel(cfg, msgBus)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if ch.Name() != "wecom" {
+			t.Errorf("Name() = %q, want %q", ch.Name(), "wecom")
+		}
+		if ch.IsRunning() {
+			t.Error("new channel should not be running")
+		}
+	})
+}
+
+func TestWeComBotChannelIsAllowed(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+
+	t.Run("empty allowlist allows all", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:      "test_token",
+			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			AllowFrom:  []string{},
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+		if !ch.IsAllowed("any_user") {
+			t.Error("empty allowlist should allow all users")
+		}
+	})
+
+	t.Run("allowlist restricts users", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:      "test_token",
+			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			AllowFrom:  []string{"allowed_user"},
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+		if !ch.IsAllowed("allowed_user") {
+			t.Error("allowed user should pass allowlist check")
+		}
+		if ch.IsAllowed("blocked_user") {
+			t.Error("non-allowed user should be blocked")
+		}
+	})
+}
+
+func TestWeComBotVerifySignature(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	cfg := config.WeComConfig{
+		Token:      "test_token",
+		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	t.Run("valid signature", func(t *testing.T) {
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		msgEncrypt := "test_message"
+		expectedSig := generateSignature("test_token", timestamp, nonce, msgEncrypt)
+
+		if !WeComVerifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
+			t.Error("valid signature should pass verification")
+		}
+	})
+
+	t.Run("invalid signature", func(t *testing.T) {
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		msgEncrypt := "test_message"
+
+		if WeComVerifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
+			t.Error("invalid signature should fail verification")
+		}
+	})
+
+	t.Run("empty token skips verification", func(t *testing.T) {
+		// Create a channel manually with empty token to test the behavior
+		cfgEmpty := config.WeComConfig{
+			Token:      "",
+			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+		}
+		base := NewBaseChannel("wecom", cfgEmpty, msgBus, cfgEmpty.AllowFrom)
+		chEmpty := &WeComBotChannel{
+			BaseChannel: base,
+			config:      cfgEmpty,
+		}
+
+		if !WeComVerifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
+			t.Error("empty token should skip verification and return true")
+		}
+	})
+}
+
+func TestWeComBotDecryptMessage(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+
+	t.Run("decrypt without AES key", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:          "test_token",
+			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			EncodingAESKey: "",
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+		// Without AES key, message should be base64 decoded only
+		plainText := "hello world"
+		encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
+
+		result, err := WeComDecryptMessage(encoded, ch.config.EncodingAESKey)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if result != plainText {
+			t.Errorf("decryptMessage() = %q, want %q", result, plainText)
+		}
+	})
+
+	t.Run("decrypt with AES key", func(t *testing.T) {
+		aesKey := generateTestAESKey()
+		cfg := config.WeComConfig{
+			Token:          "test_token",
+			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			EncodingAESKey: aesKey,
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+		originalMsg := "<xml><Content>Hello</Content></xml>"
+		encrypted, err := encryptTestMessage(originalMsg, aesKey)
+		if err != nil {
+			t.Fatalf("failed to encrypt test message: %v", err)
+		}
+
+		result, err := WeComDecryptMessage(encrypted, ch.config.EncodingAESKey)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if result != originalMsg {
+			t.Errorf("WeComDecryptMessage() = %q, want %q", result, originalMsg)
+		}
+	})
+
+	t.Run("invalid base64", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:          "test_token",
+			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			EncodingAESKey: "",
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+		_, err := WeComDecryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
+		if err == nil {
+			t.Error("expected error for invalid base64, got nil")
+		}
+	})
+
+	t.Run("invalid AES key", func(t *testing.T) {
+		cfg := config.WeComConfig{
+			Token:          "test_token",
+			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			EncodingAESKey: "invalid_key",
+		}
+		ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+		_, err := WeComDecryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
+		if err == nil {
+			t.Error("expected error for invalid AES key, got nil")
+		}
+	})
+}
+
+func TestWeComBotPKCS7Unpad(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    []byte
+		expected []byte
+	}{
+		{
+			name:     "empty input",
+			input:    []byte{},
+			expected: []byte{},
+		},
+		{
+			name:     "valid padding 3 bytes",
+			input:    append([]byte("hello"), bytes.Repeat([]byte{3}, 3)...),
+			expected: []byte("hello"),
+		},
+		{
+			name:     "valid padding 16 bytes (full block)",
+			input:    append([]byte("123456789012345"), bytes.Repeat([]byte{16}, 16)...),
+			expected: []byte("123456789012345"),
+		},
+		{
+			name:     "invalid padding larger than data",
+			input:    []byte{20},
+			expected: nil, // should return error
+		},
+		{
+			name:     "invalid padding zero",
+			input:    append([]byte("test"), byte(0)),
+			expected: nil, // should return error
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := pkcs7UnpadWeCom(tt.input)
+			if tt.expected == nil {
+				// This case should return an error
+				if err == nil {
+					t.Errorf("pkcs7UnpadWeCom() expected error for invalid padding, got result: %v", result)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("pkcs7UnpadWeCom() unexpected error: %v", err)
+				return
+			}
+			if !bytes.Equal(result, tt.expected) {
+				t.Errorf("pkcs7UnpadWeCom() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestWeComBotHandleVerification(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	aesKey := generateTestAESKey()
+	cfg := config.WeComConfig{
+		Token:          "test_token",
+		EncodingAESKey: aesKey,
+		WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	t.Run("valid verification request", func(t *testing.T) {
+		echostr := "test_echostr_123"
+		encryptedEchostr, _ := encryptTestMessage(echostr, aesKey)
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, encryptedEchostr)
+
+		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr, nil)
+		w := httptest.NewRecorder()
+
+		ch.handleVerification(context.Background(), w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
+		}
+		if w.Body.String() != echostr {
+			t.Errorf("response body = %q, want %q", w.Body.String(), echostr)
+		}
+	})
+
+	t.Run("missing parameters", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom?msg_signature=sig&timestamp=ts", nil)
+		w := httptest.NewRecorder()
+
+		ch.handleVerification(context.Background(), w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
+		}
+	})
+
+	t.Run("invalid signature", func(t *testing.T) {
+		echostr := "test_echostr"
+		encryptedEchostr, _ := encryptTestMessage(echostr, aesKey)
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+
+		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr, nil)
+		w := httptest.NewRecorder()
+
+		ch.handleVerification(context.Background(), w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
+		}
+	})
+}
+
+func TestWeComBotHandleMessageCallback(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	aesKey := generateTestAESKey()
+	cfg := config.WeComConfig{
+		Token:          "test_token",
+		EncodingAESKey: aesKey,
+		WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	t.Run("valid direct message callback", func(t *testing.T) {
+		// Create JSON message for direct chat (single)
+		jsonMsg := `{
+			"msgid": "test_msg_id_123",
+			"aibotid": "test_aibot_id",
+			"chattype": "single",
+			"from": {"userid": "user123"},
+			"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			"msgtype": "text",
+			"text": {"content": "Hello World"}
+		}`
+
+		// Encrypt message
+		encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
+
+		// Create encrypted XML wrapper
+		encryptedWrapper := struct {
+			XMLName xml.Name `xml:"xml"`
+			Encrypt string   `xml:"Encrypt"`
+		}{
+			Encrypt: encrypted,
+		}
+		wrapperData, _ := xml.Marshal(encryptedWrapper)
+
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, encrypted)
+
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce, bytes.NewReader(wrapperData))
+		w := httptest.NewRecorder()
+
+		ch.handleMessageCallback(context.Background(), w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
+		}
+		if w.Body.String() != "success" {
+			t.Errorf("response body = %q, want %q", w.Body.String(), "success")
+		}
+	})
+
+	t.Run("valid group message callback", func(t *testing.T) {
+		// Create JSON message for group chat
+		jsonMsg := `{
+			"msgid": "test_msg_id_456",
+			"aibotid": "test_aibot_id",
+			"chatid": "group_chat_id_123",
+			"chattype": "group",
+			"from": {"userid": "user456"},
+			"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			"msgtype": "text",
+			"text": {"content": "Hello Group"}
+		}`
+
+		// Encrypt message
+		encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
+
+		// Create encrypted XML wrapper
+		encryptedWrapper := struct {
+			XMLName xml.Name `xml:"xml"`
+			Encrypt string   `xml:"Encrypt"`
+		}{
+			Encrypt: encrypted,
+		}
+		wrapperData, _ := xml.Marshal(encryptedWrapper)
+
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, encrypted)
+
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce, bytes.NewReader(wrapperData))
+		w := httptest.NewRecorder()
+
+		ch.handleMessageCallback(context.Background(), w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
+		}
+		if w.Body.String() != "success" {
+			t.Errorf("response body = %q, want %q", w.Body.String(), "success")
+		}
+	})
+
+	t.Run("missing parameters", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature=sig", nil)
+		w := httptest.NewRecorder()
+
+		ch.handleMessageCallback(context.Background(), w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
+		}
+	})
+
+	t.Run("invalid XML", func(t *testing.T) {
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, "")
+
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce, strings.NewReader("invalid xml"))
+		w := httptest.NewRecorder()
+
+		ch.handleMessageCallback(context.Background(), w, req)
+
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
+		}
+	})
+
+	t.Run("invalid signature", func(t *testing.T) {
+		encryptedWrapper := struct {
+			XMLName xml.Name `xml:"xml"`
+			Encrypt string   `xml:"Encrypt"`
+		}{
+			Encrypt: "encrypted_data",
+		}
+		wrapperData, _ := xml.Marshal(encryptedWrapper)
+
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce, bytes.NewReader(wrapperData))
+		w := httptest.NewRecorder()
+
+		ch.handleMessageCallback(context.Background(), w, req)
+
+		if w.Code != http.StatusForbidden {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
+		}
+	})
+}
+
+func TestWeComBotProcessMessage(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	cfg := config.WeComConfig{
+		Token:      "test_token",
+		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	t.Run("process direct text message", func(t *testing.T) {
+		msg := WeComBotMessage{
+			MsgID:       "test_msg_id_123",
+			AIBotID:     "test_aibot_id",
+			ChatType:    "single",
+			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			MsgType:     "text",
+		}
+		msg.From.UserID = "user123"
+		msg.Text.Content = "Hello World"
+
+		// Should not panic
+		ch.processMessage(context.Background(), msg)
+	})
+
+	t.Run("process group text message", func(t *testing.T) {
+		msg := WeComBotMessage{
+			MsgID:       "test_msg_id_456",
+			AIBotID:     "test_aibot_id",
+			ChatID:      "group_chat_id_123",
+			ChatType:    "group",
+			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			MsgType:     "text",
+		}
+		msg.From.UserID = "user456"
+		msg.Text.Content = "Hello Group"
+
+		// Should not panic
+		ch.processMessage(context.Background(), msg)
+	})
+
+	t.Run("process voice message", func(t *testing.T) {
+		msg := WeComBotMessage{
+			MsgID:       "test_msg_id_789",
+			AIBotID:     "test_aibot_id",
+			ChatType:    "single",
+			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			MsgType:     "voice",
+		}
+		msg.From.UserID = "user123"
+		msg.Voice.Content = "Voice message text"
+
+		// Should not panic
+		ch.processMessage(context.Background(), msg)
+	})
+
+	t.Run("skip unsupported message type", func(t *testing.T) {
+		msg := WeComBotMessage{
+			MsgID:       "test_msg_id_000",
+			AIBotID:     "test_aibot_id",
+			ChatType:    "single",
+			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+			MsgType:     "video",
+		}
+		msg.From.UserID = "user123"
+
+		// Should not panic
+		ch.processMessage(context.Background(), msg)
+	})
+}
+
+func TestWeComBotHandleWebhook(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	cfg := config.WeComConfig{
+		Token:      "test_token",
+		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	t.Run("GET request calls verification", func(t *testing.T) {
+		echostr := "test_echostr"
+		encoded := base64.StdEncoding.EncodeToString([]byte(echostr))
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, encoded)
+
+		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encoded, nil)
+		w := httptest.NewRecorder()
+
+		ch.handleWebhook(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
+		}
+	})
+
+	t.Run("POST request calls message callback", func(t *testing.T) {
+		encryptedWrapper := struct {
+			XMLName xml.Name `xml:"xml"`
+			Encrypt string   `xml:"Encrypt"`
+		}{
+			Encrypt: base64.StdEncoding.EncodeToString([]byte("test")),
+		}
+		wrapperData, _ := xml.Marshal(encryptedWrapper)
+
+		timestamp := "1234567890"
+		nonce := "test_nonce"
+		signature := generateSignature("test_token", timestamp, nonce, encryptedWrapper.Encrypt)
+
+		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce, bytes.NewReader(wrapperData))
+		w := httptest.NewRecorder()
+
+		ch.handleWebhook(w, req)
+
+		// Should not be method not allowed
+		if w.Code == http.StatusMethodNotAllowed {
+			t.Error("POST request should not return Method Not Allowed")
+		}
+	})
+
+	t.Run("unsupported method", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPut, "/webhook/wecom", nil)
+		w := httptest.NewRecorder()
+
+		ch.handleWebhook(w, req)
+
+		if w.Code != http.StatusMethodNotAllowed {
+			t.Errorf("status code = %d, want %d", w.Code, http.StatusMethodNotAllowed)
+		}
+	})
+}
+
+func TestWeComBotHandleHealth(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+	cfg := config.WeComConfig{
+		Token:      "test_token",
+		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+	}
+	ch, _ := NewWeComBotChannel(cfg, msgBus)
+
+	req := httptest.NewRequest(http.MethodGet, "/health/wecom", nil)
+	w := httptest.NewRecorder()
+
+	ch.handleHealth(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
+	}
+
+	contentType := w.Header().Get("Content-Type")
+	if contentType != "application/json" {
+		t.Errorf("Content-Type = %q, want %q", contentType, "application/json")
+	}
+
+	body := w.Body.String()
+	if !strings.Contains(body, "status") || !strings.Contains(body, "running") {
+		t.Errorf("response body should contain status and running fields, got: %s", body)
+	}
+}
+
+func TestWeComBotReplyMessage(t *testing.T) {
+	msg := WeComBotReplyMessage{
+		MsgType: "text",
+	}
+	msg.Text.Content = "Hello World"
+
+	if msg.MsgType != "text" {
+		t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
+	}
+	if msg.Text.Content != "Hello World" {
+		t.Errorf("Text.Content = %q, want %q", msg.Text.Content, "Hello World")
+	}
+}
+
+func TestWeComBotMessageStructure(t *testing.T) {
+	jsonData := `{
+		"msgid": "test_msg_id_123",
+		"aibotid": "test_aibot_id",
+		"chatid": "group_chat_id_123",
+		"chattype": "group",
+		"from": {"userid": "user123"},
+		"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
+		"msgtype": "text",
+		"text": {"content": "Hello World"}
+	}`
+
+	var msg WeComBotMessage
+	err := json.Unmarshal([]byte(jsonData), &msg)
+	if err != nil {
+		t.Fatalf("failed to unmarshal JSON: %v", err)
+	}
+
+	if msg.MsgID != "test_msg_id_123" {
+		t.Errorf("MsgID = %q, want %q", msg.MsgID, "test_msg_id_123")
+	}
+	if msg.AIBotID != "test_aibot_id" {
+		t.Errorf("AIBotID = %q, want %q", msg.AIBotID, "test_aibot_id")
+	}
+	if msg.ChatID != "group_chat_id_123" {
+		t.Errorf("ChatID = %q, want %q", msg.ChatID, "group_chat_id_123")
+	}
+	if msg.ChatType != "group" {
+		t.Errorf("ChatType = %q, want %q", msg.ChatType, "group")
+	}
+	if msg.From.UserID != "user123" {
+		t.Errorf("From.UserID = %q, want %q", msg.From.UserID, "user123")
+	}
+	if msg.MsgType != "text" {
+		t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
+	}
+	if msg.Text.Content != "Hello World" {
+		t.Errorf("Text.Content = %q, want %q", msg.Text.Content, "Hello World")
+	}
+}
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@ -191,6 +191,8 @@ type ChannelsConfig struct {
 	Slack    SlackConfig    `json:"slack"`
 	LINE     LINEConfig     `json:"line"`
 	OneBot   OneBotConfig   `json:"onebot"`
+	WeCom    WeComConfig    `json:"wecom"`
+	WeComApp WeComAppConfig `json:"wecom_app"`
 }

 type WhatsAppConfig struct {
@ -219,6 +221,7 @@ type DiscordConfig struct {
 	Enabled     bool                `json:"enabled" env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
 	Token       string              `json:"token" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
 	AllowFrom   FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
+	MentionOnly bool                `json:"mention_only" env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
 }

 type MaixCamConfig struct {
@ -268,6 +271,32 @@ type OneBotConfig struct {
 	AllowFrom          FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_ONEBOT_ALLOW_FROM"`
 }

+type WeComConfig struct {
+	Enabled        bool                `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_ENABLED"`
+	Token          string              `json:"token" env:"PICOCLAW_CHANNELS_WECOM_TOKEN"`
+	EncodingAESKey string              `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY"`
+	WebhookURL     string              `json:"webhook_url" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_URL"`
+	WebhookHost    string              `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_HOST"`
+	WebhookPort    int                 `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PORT"`
+	WebhookPath    string              `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PATH"`
+	AllowFrom      FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_ALLOW_FROM"`
+	ReplyTimeout   int                 `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_REPLY_TIMEOUT"`
+}
+
+type WeComAppConfig struct {
+	Enabled        bool                `json:"enabled" env:"PICOCLAW_CHANNELS_WECOM_APP_ENABLED"`
+	CorpID         string              `json:"corp_id" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_ID"`
+	CorpSecret     string              `json:"corp_secret" env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_SECRET"`
+	AgentID        int64               `json:"agent_id" env:"PICOCLAW_CHANNELS_WECOM_APP_AGENT_ID"`
+	Token          string              `json:"token" env:"PICOCLAW_CHANNELS_WECOM_APP_TOKEN"`
+	EncodingAESKey string              `json:"encoding_aes_key" env:"PICOCLAW_CHANNELS_WECOM_APP_ENCODING_AES_KEY"`
+	WebhookHost    string              `json:"webhook_host" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_HOST"`
+	WebhookPort    int                 `json:"webhook_port" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PORT"`
+	WebhookPath    string              `json:"webhook_path" env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PATH"`
+	AllowFrom      FlexibleStringSlice `json:"allow_from" env:"PICOCLAW_CHANNELS_WECOM_APP_ALLOW_FROM"`
+	ReplyTimeout   int                 `json:"reply_timeout" env:"PICOCLAW_CHANNELS_WECOM_APP_REPLY_TIMEOUT"`
+}
+
 type HeartbeatConfig struct {
 	Enabled  bool `json:"enabled" env:"PICOCLAW_HEARTBEAT_ENABLED"`
 	Interval int  `json:"interval" env:"PICOCLAW_HEARTBEAT_INTERVAL"` // minutes, min 5
@ -509,9 +538,37 @@ type ToolsConfig struct {
 	Web    WebToolsConfig    `json:"web"`
 	Cron   CronToolsConfig   `json:"cron"`
 	Exec   ExecConfig        `json:"exec"`
+	Skills SkillsToolsConfig `json:"skills"`
 	Sandbox SandboxToolsConfig `json:"sandbox"`
 }

+type SkillsToolsConfig struct {
+	Registries            SkillsRegistriesConfig `json:"registries"`
+	MaxConcurrentSearches int                    `json:"max_concurrent_searches" env:"PICOCLAW_SKILLS_MAX_CONCURRENT_SEARCHES"`
+	SearchCache           SearchCacheConfig      `json:"search_cache"`
+}
+
+type SearchCacheConfig struct {
+	MaxSize    int `json:"max_size" env:"PICOCLAW_SKILLS_SEARCH_CACHE_MAX_SIZE"`
+	TTLSeconds int `json:"ttl_seconds" env:"PICOCLAW_SKILLS_SEARCH_CACHE_TTL_SECONDS"`
+}
+
+type SkillsRegistriesConfig struct {
+	ClawHub ClawHubRegistryConfig `json:"clawhub"`
+}
+
+type ClawHubRegistryConfig struct {
+	Enabled         bool   `json:"enabled" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED"`
+	BaseURL         string `json:"base_url" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL"`
+	AuthToken       string `json:"auth_token" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN"`
+	SearchPath      string `json:"search_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SEARCH_PATH"`
+	SkillsPath      string `json:"skills_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SKILLS_PATH"`
+	DownloadPath    string `json:"download_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_DOWNLOAD_PATH"`
+	Timeout         int    `json:"timeout" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_TIMEOUT"`
+	MaxZipSize      int    `json:"max_zip_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_ZIP_SIZE"`
+	MaxResponseSize int    `json:"max_response_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_RESPONSE_SIZE"`
+}
+
 func LoadConfig(path string) (*Config, error) {
 	cfg := DefaultConfig()

--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@ -80,6 +80,7 @@ func DefaultConfig() *Config {
 				Enabled:     false,
 				Token:       "",
 				AllowFrom:   FlexibleStringSlice{},
+				MentionOnly: false,
 			},
 			MaixCam: MaixCamConfig{
 				Enabled:   false,
@ -122,6 +123,30 @@ func DefaultConfig() *Config {
 				GroupTriggerPrefix: []string{},
 				AllowFrom:          FlexibleStringSlice{},
 			},
+			WeCom: WeComConfig{
+				Enabled:        false,
+				Token:          "",
+				EncodingAESKey: "",
+				WebhookURL:     "",
+				WebhookHost:    "0.0.0.0",
+				WebhookPort:    18793,
+				WebhookPath:    "/webhook/wecom",
+				AllowFrom:      FlexibleStringSlice{},
+				ReplyTimeout:   5,
+			},
+			WeComApp: WeComAppConfig{
+				Enabled:        false,
+				CorpID:         "",
+				CorpSecret:     "",
+				AgentID:        0,
+				Token:          "",
+				EncodingAESKey: "",
+				WebhookHost:    "0.0.0.0",
+				WebhookPort:    18792,
+				WebhookPath:    "/webhook/wecom-app",
+				AllowFrom:      FlexibleStringSlice{},
+				ReplyTimeout:   5,
+			},
 		},
 		Providers: ProvidersConfig{
 			OpenAI: OpenAIProviderConfig{WebSearch: true},
@ -296,6 +321,22 @@ func DefaultConfig() *Config {
 			Cron: CronToolsConfig{
 				ExecTimeoutMinutes: 5,
 			},
+			Exec: ExecConfig{
+				EnableDenyPatterns: true,
+			},
+			Skills: SkillsToolsConfig{
+				Registries: SkillsRegistriesConfig{
+					ClawHub: ClawHubRegistryConfig{
+						Enabled: true,
+						BaseURL: "https://clawhub.ai",
+					},
+				},
+				MaxConcurrentSearches: 2,
+				SearchCache: SearchCacheConfig{
+					MaxSize:    50,
+					TTLSeconds: 300,
+				},
+			},
 			Sandbox: SandboxToolsConfig{
 				Tools: SandboxToolPolicyConfig{
 					Allow: []string{"exec", "read_file", "write_file"},
--- a/pkg/skills/clawhub_registry.go
+++ b/pkg/skills/clawhub_registry.go
@ -0,0 +1,311 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+const (
+	defaultClawHubTimeout  = 30 * time.Second
+	defaultMaxZipSize      = 50 * 1024 * 1024 // 50 MB
+	defaultMaxResponseSize = 2 * 1024 * 1024  // 2 MB
+)
+
+// ClawHubRegistry implements SkillRegistry for the ClawHub platform.
+type ClawHubRegistry struct {
+	baseURL         string
+	authToken       string // Optional - for elevated rate limits
+	searchPath      string // Search API
+	skillsPath      string // For retrieving skill metadata
+	downloadPath    string // For fetching ZIP files for download
+	maxZipSize      int
+	maxResponseSize int
+	client          *http.Client
+}
+
+// NewClawHubRegistry creates a new ClawHub registry client from config.
+func NewClawHubRegistry(cfg ClawHubConfig) *ClawHubRegistry {
+	baseURL := cfg.BaseURL
+	if baseURL == "" {
+		baseURL = "https://clawhub.ai"
+	}
+	searchPath := cfg.SearchPath
+	if searchPath == "" {
+		searchPath = "/api/v1/search"
+	}
+	skillsPath := cfg.SkillsPath
+	if skillsPath == "" {
+		skillsPath = "/api/v1/skills"
+	}
+	downloadPath := cfg.DownloadPath
+	if downloadPath == "" {
+		downloadPath = "/api/v1/download"
+	}
+
+	timeout := defaultClawHubTimeout
+	if cfg.Timeout > 0 {
+		timeout = time.Duration(cfg.Timeout) * time.Second
+	}
+
+	maxZip := defaultMaxZipSize
+	if cfg.MaxZipSize > 0 {
+		maxZip = cfg.MaxZipSize
+	}
+
+	maxResp := defaultMaxResponseSize
+	if cfg.MaxResponseSize > 0 {
+		maxResp = cfg.MaxResponseSize
+	}
+
+	return &ClawHubRegistry{
+		baseURL:         baseURL,
+		authToken:       cfg.AuthToken,
+		searchPath:      searchPath,
+		skillsPath:      skillsPath,
+		downloadPath:    downloadPath,
+		maxZipSize:      maxZip,
+		maxResponseSize: maxResp,
+		client: &http.Client{
+			Timeout: timeout,
+			Transport: &http.Transport{
+				MaxIdleConns:        5,
+				IdleConnTimeout:     30 * time.Second,
+				TLSHandshakeTimeout: 10 * time.Second,
+			},
+		},
+	}
+}
+
+func (c *ClawHubRegistry) Name() string {
+	return "clawhub"
+}
+
+// --- Search ---
+
+type clawhubSearchResponse struct {
+	Results []clawhubSearchResult `json:"results"`
+}
+
+type clawhubSearchResult struct {
+	Score       float64 `json:"score"`
+	Slug        *string `json:"slug"`
+	DisplayName *string `json:"displayName"`
+	Summary     *string `json:"summary"`
+	Version     *string `json:"version"`
+}
+
+func (c *ClawHubRegistry) Search(ctx context.Context, query string, limit int) ([]SearchResult, error) {
+	u, err := url.Parse(c.baseURL + c.searchPath)
+	if err != nil {
+		return nil, fmt.Errorf("invalid base URL: %w", err)
+	}
+
+	q := u.Query()
+	q.Set("q", query)
+	if limit > 0 {
+		q.Set("limit", fmt.Sprintf("%d", limit))
+	}
+	u.RawQuery = q.Encode()
+
+	body, err := c.doGet(ctx, u.String())
+	if err != nil {
+		return nil, fmt.Errorf("search request failed: %w", err)
+	}
+
+	var resp clawhubSearchResponse
+	if err := json.Unmarshal(body, &resp); err != nil {
+		return nil, fmt.Errorf("failed to parse search response: %w", err)
+	}
+
+	results := make([]SearchResult, 0, len(resp.Results))
+	for _, r := range resp.Results {
+		slug := utils.DerefStr(r.Slug, "")
+		if slug == "" {
+			continue
+		}
+
+		summary := utils.DerefStr(r.Summary, "")
+		if summary == "" {
+			continue
+		}
+
+		displayName := utils.DerefStr(r.DisplayName, "")
+		if displayName == "" {
+			displayName = slug
+		}
+
+		results = append(results, SearchResult{
+			Score:        r.Score,
+			Slug:         slug,
+			DisplayName:  displayName,
+			Summary:      summary,
+			Version:      utils.DerefStr(r.Version, ""),
+			RegistryName: c.Name(),
+		})
+	}
+
+	return results, nil
+}
+
+// --- GetSkillMeta ---
+
+type clawhubSkillResponse struct {
+	Slug          string                 `json:"slug"`
+	DisplayName   string                 `json:"displayName"`
+	Summary       string                 `json:"summary"`
+	LatestVersion *clawhubVersionInfo    `json:"latestVersion"`
+	Moderation    *clawhubModerationInfo `json:"moderation"`
+}
+
+type clawhubVersionInfo struct {
+	Version string `json:"version"`
+}
+
+type clawhubModerationInfo struct {
+	IsMalwareBlocked bool `json:"isMalwareBlocked"`
+	IsSuspicious     bool `json:"isSuspicious"`
+}
+
+func (c *ClawHubRegistry) GetSkillMeta(ctx context.Context, slug string) (*SkillMeta, error) {
+	if err := utils.ValidateSkillIdentifier(slug); err != nil {
+		return nil, fmt.Errorf("invalid slug %q: error: %s", slug, err.Error())
+	}
+
+	u := c.baseURL + c.skillsPath + "/" + url.PathEscape(slug)
+
+	body, err := c.doGet(ctx, u)
+	if err != nil {
+		return nil, fmt.Errorf("skill metadata request failed: %w", err)
+	}
+
+	var resp clawhubSkillResponse
+	if err := json.Unmarshal(body, &resp); err != nil {
+		return nil, fmt.Errorf("failed to parse skill metadata: %w", err)
+	}
+
+	meta := &SkillMeta{
+		Slug:         resp.Slug,
+		DisplayName:  resp.DisplayName,
+		Summary:      resp.Summary,
+		RegistryName: c.Name(),
+	}
+
+	if resp.LatestVersion != nil {
+		meta.LatestVersion = resp.LatestVersion.Version
+	}
+	if resp.Moderation != nil {
+		meta.IsMalwareBlocked = resp.Moderation.IsMalwareBlocked
+		meta.IsSuspicious = resp.Moderation.IsSuspicious
+	}
+
+	return meta, nil
+}
+
+// --- DownloadAndInstall ---
+
+// DownloadAndInstall fetches metadata (with fallback), resolves version,
+// downloads the skill ZIP, and extracts it to targetDir.
+// Returns an InstallResult for the caller to use for moderation decisions.
+func (c *ClawHubRegistry) DownloadAndInstall(ctx context.Context, slug, version, targetDir string) (*InstallResult, error) {
+	if err := utils.ValidateSkillIdentifier(slug); err != nil {
+		return nil, fmt.Errorf("invalid slug %q: error: %s", slug, err.Error())
+	}
+
+	// Step 1: Fetch metadata (with fallback).
+	result := &InstallResult{}
+	meta, err := c.GetSkillMeta(ctx, slug)
+	if err != nil {
+		// Fallback: proceed without metadata.
+		meta = nil
+	}
+
+	if meta != nil {
+		result.IsMalwareBlocked = meta.IsMalwareBlocked
+		result.IsSuspicious = meta.IsSuspicious
+		result.Summary = meta.Summary
+	}
+
+	// Step 2: Resolve version.
+	installVersion := version
+	if installVersion == "" && meta != nil {
+		installVersion = meta.LatestVersion
+	}
+	if installVersion == "" {
+		installVersion = "latest"
+	}
+	result.Version = installVersion
+
+	// Step 3: Download ZIP to temp file (streams in ~32KB chunks).
+	u, err := url.Parse(c.baseURL + c.downloadPath)
+	if err != nil {
+		return nil, fmt.Errorf("invalid base URL: %w", err)
+	}
+
+	q := u.Query()
+	q.Set("slug", slug)
+	if installVersion != "latest" {
+		q.Set("version", installVersion)
+	}
+	u.RawQuery = q.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+	if c.authToken != "" {
+		req.Header.Set("Authorization", "Bearer "+c.authToken)
+	}
+
+	tmpPath, err := utils.DownloadToFile(ctx, c.client, req, int64(c.maxZipSize))
+	if err != nil {
+		return nil, fmt.Errorf("download failed: %w", err)
+	}
+	defer os.Remove(tmpPath)
+
+	// Step 4: Extract from file on disk.
+	if err := utils.ExtractZipFile(tmpPath, targetDir); err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}
+
+// --- HTTP helper ---
+
+func (c *ClawHubRegistry) doGet(ctx context.Context, urlStr string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Accept", "application/json")
+	if c.authToken != "" {
+		req.Header.Set("Authorization", "Bearer "+c.authToken)
+	}
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	// Limit response body read to prevent memory issues.
+	body, err := io.ReadAll(io.LimitReader(resp.Body, int64(c.maxResponseSize)))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	return body, nil
+}
--- a/pkg/skills/clawhub_registry_test.go
+++ b/pkg/skills/clawhub_registry_test.go
@ -0,0 +1,256 @@
+package skills
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/utils"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func newTestRegistry(serverURL, authToken string) *ClawHubRegistry {
+	return NewClawHubRegistry(ClawHubConfig{
+		Enabled:   true,
+		BaseURL:   serverURL,
+		AuthToken: authToken,
+	})
+}
+
+func TestClawHubRegistrySearch(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/search", r.URL.Path)
+		assert.Equal(t, "github", r.URL.Query().Get("q"))
+
+		slug := "github"
+		name := "GitHub Integration"
+		summary := "Interact with GitHub repos"
+		version := "1.0.0"
+
+		json.NewEncoder(w).Encode(clawhubSearchResponse{
+			Results: []clawhubSearchResult{
+				{Score: 0.95, Slug: &slug, DisplayName: &name, Summary: &summary, Version: &version},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "")
+	results, err := reg.Search(context.Background(), "github", 5)
+
+	require.NoError(t, err)
+	require.Len(t, results, 1)
+	assert.Equal(t, "github", results[0].Slug)
+	assert.Equal(t, "GitHub Integration", results[0].DisplayName)
+	assert.InDelta(t, 0.95, results[0].Score, 0.001)
+	assert.Equal(t, "clawhub", results[0].RegistryName)
+}
+
+func TestClawHubRegistryGetSkillMeta(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/api/v1/skills/github", r.URL.Path)
+
+		json.NewEncoder(w).Encode(clawhubSkillResponse{
+			Slug:        "github",
+			DisplayName: "GitHub Integration",
+			Summary:     "Full GitHub API integration",
+			LatestVersion: &clawhubVersionInfo{
+				Version: "2.1.0",
+			},
+			Moderation: &clawhubModerationInfo{
+				IsMalwareBlocked: false,
+				IsSuspicious:     true,
+			},
+		})
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "")
+	meta, err := reg.GetSkillMeta(context.Background(), "github")
+
+	require.NoError(t, err)
+	assert.Equal(t, "github", meta.Slug)
+	assert.Equal(t, "2.1.0", meta.LatestVersion)
+	assert.False(t, meta.IsMalwareBlocked)
+	assert.True(t, meta.IsSuspicious)
+}
+
+func TestClawHubRegistryGetSkillMetaUnsafeSlug(t *testing.T) {
+	reg := newTestRegistry("https://example.com", "")
+	_, err := reg.GetSkillMeta(context.Background(), "../etc/passwd")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid slug")
+}
+
+func TestClawHubRegistryDownloadAndInstall(t *testing.T) {
+	// Create a valid ZIP in memory.
+	zipBuf := createTestZip(t, map[string]string{
+		"SKILL.md":  "---\nname: test-skill\ndescription: A test\n---\nHello skill",
+		"README.md": "# Test Skill\n",
+	})
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/skills/test-skill":
+			// Metadata endpoint.
+			json.NewEncoder(w).Encode(clawhubSkillResponse{
+				Slug:          "test-skill",
+				DisplayName:   "Test Skill",
+				Summary:       "A test skill",
+				LatestVersion: &clawhubVersionInfo{Version: "1.0.0"},
+			})
+		case "/api/v1/download":
+			assert.Equal(t, "test-skill", r.URL.Query().Get("slug"))
+			w.Header().Set("Content-Type", "application/zip")
+			w.Write(zipBuf)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	tmpDir := t.TempDir()
+	targetDir := filepath.Join(tmpDir, "test-skill")
+
+	reg := newTestRegistry(srv.URL, "")
+	result, err := reg.DownloadAndInstall(context.Background(), "test-skill", "1.0.0", targetDir)
+
+	require.NoError(t, err)
+	assert.Equal(t, "1.0.0", result.Version)
+	assert.False(t, result.IsMalwareBlocked)
+
+	// Verify extracted files.
+	skillContent, err := os.ReadFile(filepath.Join(targetDir, "SKILL.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(skillContent), "Hello skill")
+
+	readmeContent, err := os.ReadFile(filepath.Join(targetDir, "README.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(readmeContent), "# Test Skill")
+}
+
+func TestClawHubRegistryAuthToken(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authHeader := r.Header.Get("Authorization")
+		assert.Equal(t, "Bearer test-token-123", authHeader)
+		json.NewEncoder(w).Encode(clawhubSearchResponse{Results: nil})
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "test-token-123")
+	_, _ = reg.Search(context.Background(), "test", 5)
+}
+
+func TestExtractZipPathTraversal(t *testing.T) {
+	// Create a ZIP with a path traversal entry.
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+
+	// Malicious entry trying to escape directory.
+	w, err := zw.Create("../../etc/passwd")
+	require.NoError(t, err)
+	w.Write([]byte("malicious"))
+
+	zw.Close()
+
+	// Write to temp file for extractZipFile.
+	tmpZip := filepath.Join(t.TempDir(), "bad.zip")
+	require.NoError(t, os.WriteFile(tmpZip, buf.Bytes(), 0644))
+
+	tmpDir := t.TempDir()
+	err = utils.ExtractZipFile(tmpZip, tmpDir)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "unsafe path")
+}
+
+func TestExtractZipWithSubdirectories(t *testing.T) {
+	zipBuf := createTestZip(t, map[string]string{
+		"SKILL.md":           "root file",
+		"scripts/helper.sh":  "#!/bin/bash\necho hello",
+		"examples/demo.yaml": "key: value",
+	})
+
+	// Write to temp file for extractZipFile.
+	tmpZip := filepath.Join(t.TempDir(), "test.zip")
+	require.NoError(t, os.WriteFile(tmpZip, zipBuf, 0644))
+
+	tmpDir := t.TempDir()
+	targetDir := filepath.Join(tmpDir, "my-skill")
+
+	err := utils.ExtractZipFile(tmpZip, targetDir)
+	require.NoError(t, err)
+
+	// Verify nested file.
+	data, err := os.ReadFile(filepath.Join(targetDir, "scripts", "helper.sh"))
+	require.NoError(t, err)
+	assert.Contains(t, string(data), "#!/bin/bash")
+}
+
+func TestClawHubRegistrySearchHTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte("Internal Server Error"))
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "")
+	_, err := reg.Search(context.Background(), "test", 5)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "500")
+}
+
+func TestClawHubRegistrySearchNullableFields(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		validSlug := "valid-slug"
+		validSummary := "valid summary"
+
+		// Return results with various null/empty fields
+		json.NewEncoder(w).Encode(clawhubSearchResponse{
+			Results: []clawhubSearchResult{
+				// Case 1: Null Slug -> Skip
+				{Score: 0.1, Slug: nil, DisplayName: nil, Summary: nil, Version: nil},
+				// Case 2: Valid Slug, Null Summary -> Skip
+				{Score: 0.2, Slug: &validSlug, DisplayName: nil, Summary: nil, Version: nil},
+				// Case 3: Valid Slug, Valid Summary, Null Name -> Keep, Name=Slug
+				{Score: 0.8, Slug: &validSlug, DisplayName: nil, Summary: &validSummary, Version: nil},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "")
+	results, err := reg.Search(context.Background(), "test", 5)
+
+	require.NoError(t, err)
+	require.Len(t, results, 1, "should only return 1 valid result")
+
+	r := results[0]
+	assert.Equal(t, "valid-slug", r.Slug)
+	assert.Equal(t, "valid-slug", r.DisplayName, "should fallback name to slug")
+	assert.Equal(t, "valid summary", r.Summary)
+}
+
+// --- helpers ---
+
+func createTestZip(t *testing.T, files map[string]string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+
+	for name, content := range files {
+		w, err := zw.Create(name)
+		require.NoError(t, err)
+		_, err = w.Write([]byte(content))
+		require.NoError(t, err)
+	}
+
+	require.NoError(t, zw.Close())
+	return buf.Bytes()
+}
--- a/pkg/skills/registry.go
+++ b/pkg/skills/registry.go
@ -0,0 +1,223 @@
+package skills
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+)
+
+const (
+	defaultMaxConcurrentSearches = 2
+)
+
+// SearchResult represents a single result from a skill registry search.
+type SearchResult struct {
+	Score        float64 `json:"score"`
+	Slug         string  `json:"slug"`
+	DisplayName  string  `json:"display_name"`
+	Summary      string  `json:"summary"`
+	Version      string  `json:"version"`
+	RegistryName string  `json:"registry_name"`
+}
+
+// SkillMeta holds metadata about a skill from a registry.
+type SkillMeta struct {
+	Slug             string `json:"slug"`
+	DisplayName      string `json:"display_name"`
+	Summary          string `json:"summary"`
+	LatestVersion    string `json:"latest_version"`
+	IsMalwareBlocked bool   `json:"is_malware_blocked"`
+	IsSuspicious     bool   `json:"is_suspicious"`
+	RegistryName     string `json:"registry_name"`
+}
+
+// InstallResult is returned by DownloadAndInstall to carry metadata
+// back to the caller for moderation and user messaging.
+type InstallResult struct {
+	Version          string
+	IsMalwareBlocked bool
+	IsSuspicious     bool
+	Summary          string
+}
+
+// SkillRegistry is the interface that all skill registries must implement.
+// Each registry represents a different source of skills (e.g., clawhub.ai)
+type SkillRegistry interface {
+	// Name returns the unique name of this registry (e.g., "clawhub").
+	Name() string
+	// Search searches the registry for skills matching the query.
+	Search(ctx context.Context, query string, limit int) ([]SearchResult, error)
+	// GetSkillMeta retrieves metadata for a specific skill by slug.
+	GetSkillMeta(ctx context.Context, slug string) (*SkillMeta, error)
+	// DownloadAndInstall fetches metadata, resolves the version, downloads and
+	// installs the skill to targetDir. Returns an InstallResult with metadata
+	// for the caller to use for moderation and user messaging.
+	DownloadAndInstall(ctx context.Context, slug, version, targetDir string) (*InstallResult, error)
+}
+
+// RegistryConfig holds configuration for all skill registries.
+// This is the input to NewRegistryManagerFromConfig.
+type RegistryConfig struct {
+	ClawHub               ClawHubConfig
+	MaxConcurrentSearches int
+}
+
+// ClawHubConfig configures the ClawHub registry.
+type ClawHubConfig struct {
+	Enabled         bool
+	BaseURL         string
+	AuthToken       string
+	SearchPath      string // e.g. "/api/v1/search"
+	SkillsPath      string // e.g. "/api/v1/skills"
+	DownloadPath    string // e.g. "/api/v1/download"
+	Timeout         int    // seconds, 0 = default (30s)
+	MaxZipSize      int    // bytes, 0 = default (50MB)
+	MaxResponseSize int    // bytes, 0 = default (2MB)
+}
+
+// RegistryManager coordinates multiple skill registries.
+// It fans out search requests and routes installs to the correct registry.
+type RegistryManager struct {
+	registries    []SkillRegistry
+	maxConcurrent int
+	mu            sync.RWMutex
+}
+
+// NewRegistryManager creates an empty RegistryManager.
+func NewRegistryManager() *RegistryManager {
+	return &RegistryManager{
+		registries:    make([]SkillRegistry, 0),
+		maxConcurrent: defaultMaxConcurrentSearches,
+	}
+}
+
+// NewRegistryManagerFromConfig builds a RegistryManager from config,
+// instantiating only the enabled registries.
+func NewRegistryManagerFromConfig(cfg RegistryConfig) *RegistryManager {
+	rm := NewRegistryManager()
+	if cfg.MaxConcurrentSearches > 0 {
+		rm.maxConcurrent = cfg.MaxConcurrentSearches
+	}
+	if cfg.ClawHub.Enabled {
+		rm.AddRegistry(NewClawHubRegistry(cfg.ClawHub))
+	}
+	return rm
+}
+
+// AddRegistry adds a registry to the manager.
+func (rm *RegistryManager) AddRegistry(r SkillRegistry) {
+	rm.mu.Lock()
+	defer rm.mu.Unlock()
+	rm.registries = append(rm.registries, r)
+}
+
+// GetRegistry returns a registry by name, or nil if not found.
+func (rm *RegistryManager) GetRegistry(name string) SkillRegistry {
+	rm.mu.RLock()
+	defer rm.mu.RUnlock()
+	for _, r := range rm.registries {
+		if r.Name() == name {
+			return r
+		}
+	}
+	return nil
+}
+
+// SearchAll fans out the query to all registries concurrently
+// and merges results sorted by score descending.
+func (rm *RegistryManager) SearchAll(ctx context.Context, query string, limit int) ([]SearchResult, error) {
+	rm.mu.RLock()
+	regs := make([]SkillRegistry, len(rm.registries))
+	copy(regs, rm.registries)
+	rm.mu.RUnlock()
+
+	if len(regs) == 0 {
+		return nil, fmt.Errorf("no registries configured")
+	}
+
+	type regResult struct {
+		results []SearchResult
+		err     error
+	}
+
+	// Semaphore: limit concurrency.
+	sem := make(chan struct{}, rm.maxConcurrent)
+	resultsCh := make(chan regResult, len(regs))
+
+	var wg sync.WaitGroup
+	for _, reg := range regs {
+		wg.Add(1)
+		go func(r SkillRegistry) {
+			defer wg.Done()
+
+			// Acquire semaphore slot.
+			select {
+			case sem <- struct{}{}:
+				defer func() { <-sem }()
+			case <-ctx.Done():
+				resultsCh <- regResult{err: ctx.Err()}
+				return
+			}
+
+			searchCtx, cancel := context.WithTimeout(ctx, 1*time.Minute)
+			defer cancel()
+
+			results, err := r.Search(searchCtx, query, limit)
+			if err != nil {
+				slog.Warn("registry search failed", "registry", r.Name(), "error", err)
+				resultsCh <- regResult{err: err}
+				return
+			}
+			resultsCh <- regResult{results: results}
+		}(reg)
+	}
+
+	// Close results channel after all goroutines complete.
+	go func() {
+		wg.Wait()
+		close(resultsCh)
+	}()
+
+	var merged []SearchResult
+	var lastErr error
+
+	var anyRegistrySucceeded bool
+	for rr := range resultsCh {
+		if rr.err != nil {
+			lastErr = rr.err
+			continue
+		}
+		anyRegistrySucceeded = true
+		merged = append(merged, rr.results...)
+	}
+
+	// If all registries failed, return the last error.
+	if !anyRegistrySucceeded && lastErr != nil {
+		return nil, fmt.Errorf("all registries failed: %w", lastErr)
+	}
+
+	// Sort by score descending.
+	sortByScoreDesc(merged)
+
+	// Clamp to limit.
+	if limit > 0 && len(merged) > limit {
+		merged = merged[:limit]
+	}
+
+	return merged, nil
+}
+
+// sortByScoreDesc sorts SearchResults by Score in descending order (insertion sort — small slices).
+func sortByScoreDesc(results []SearchResult) {
+	for i := 1; i < len(results); i++ {
+		key := results[i]
+		j := i - 1
+		for j >= 0 && results[j].Score < key.Score {
+			results[j+1] = results[j]
+			j--
+		}
+		results[j+1] = key
+	}
+}
--- a/pkg/skills/registry_test.go
+++ b/pkg/skills/registry_test.go
@ -0,0 +1,179 @@
+package skills
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/utils"
+	"github.com/stretchr/testify/assert"
+)
+
+// mockRegistry is a test double implementing SkillRegistry.
+type mockRegistry struct {
+	name          string
+	searchResults []SearchResult
+	searchErr     error
+	meta          *SkillMeta
+	metaErr       error
+	installResult *InstallResult
+	installErr    error
+}
+
+func (m *mockRegistry) Name() string { return m.name }
+
+func (m *mockRegistry) Search(_ context.Context, _ string, _ int) ([]SearchResult, error) {
+	return m.searchResults, m.searchErr
+}
+
+func (m *mockRegistry) GetSkillMeta(_ context.Context, _ string) (*SkillMeta, error) {
+	return m.meta, m.metaErr
+}
+
+func (m *mockRegistry) DownloadAndInstall(_ context.Context, _, _, _ string) (*InstallResult, error) {
+	return m.installResult, m.installErr
+}
+
+func TestRegistryManagerSearchAllSingle(t *testing.T) {
+	mgr := NewRegistryManager()
+	mgr.AddRegistry(&mockRegistry{
+		name: "test",
+		searchResults: []SearchResult{
+			{Slug: "skill-a", Score: 0.9, RegistryName: "test"},
+			{Slug: "skill-b", Score: 0.5, RegistryName: "test"},
+		},
+	})
+
+	results, err := mgr.SearchAll(context.Background(), "test query", 10)
+	assert.NoError(t, err)
+	assert.Len(t, results, 2)
+	assert.Equal(t, "skill-a", results[0].Slug)
+}
+
+func TestRegistryManagerSearchAllMultiple(t *testing.T) {
+	mgr := NewRegistryManager()
+	mgr.AddRegistry(&mockRegistry{
+		name: "alpha",
+		searchResults: []SearchResult{
+			{Slug: "skill-a", Score: 0.8, RegistryName: "alpha"},
+		},
+	})
+	mgr.AddRegistry(&mockRegistry{
+		name: "beta",
+		searchResults: []SearchResult{
+			{Slug: "skill-b", Score: 0.95, RegistryName: "beta"},
+		},
+	})
+
+	results, err := mgr.SearchAll(context.Background(), "test query", 10)
+	assert.NoError(t, err)
+	assert.Len(t, results, 2)
+	// Should be sorted by score descending
+	assert.Equal(t, "skill-b", results[0].Slug)
+	assert.Equal(t, "skill-a", results[1].Slug)
+}
+
+func TestRegistryManagerSearchAllOneFailsGracefully(t *testing.T) {
+	mgr := NewRegistryManager()
+	mgr.AddRegistry(&mockRegistry{
+		name:      "failing",
+		searchErr: fmt.Errorf("network error"),
+	})
+	mgr.AddRegistry(&mockRegistry{
+		name: "working",
+		searchResults: []SearchResult{
+			{Slug: "skill-a", Score: 0.8, RegistryName: "working"},
+		},
+	})
+
+	results, err := mgr.SearchAll(context.Background(), "test query", 10)
+	assert.NoError(t, err)
+	assert.Len(t, results, 1)
+	assert.Equal(t, "skill-a", results[0].Slug)
+}
+
+func TestRegistryManagerSearchAllAllFail(t *testing.T) {
+	mgr := NewRegistryManager()
+	mgr.AddRegistry(&mockRegistry{
+		name:      "fail-1",
+		searchErr: fmt.Errorf("error 1"),
+	})
+
+	_, err := mgr.SearchAll(context.Background(), "test query", 10)
+	assert.Error(t, err)
+}
+
+func TestRegistryManagerSearchAllNoRegistries(t *testing.T) {
+	mgr := NewRegistryManager()
+	_, err := mgr.SearchAll(context.Background(), "test query", 10)
+	assert.Error(t, err)
+}
+
+func TestRegistryManagerGetRegistry(t *testing.T) {
+	mgr := NewRegistryManager()
+	mock := &mockRegistry{name: "clawhub"}
+	mgr.AddRegistry(mock)
+
+	got := mgr.GetRegistry("clawhub")
+	assert.NotNil(t, got)
+	assert.Equal(t, "clawhub", got.Name())
+
+	got = mgr.GetRegistry("nonexistent")
+	assert.Nil(t, got)
+}
+
+func TestRegistryManagerSearchAllRespectLimit(t *testing.T) {
+	mgr := NewRegistryManager()
+	results := make([]SearchResult, 20)
+	for i := range results {
+		results[i] = SearchResult{Slug: fmt.Sprintf("skill-%d", i), Score: float64(20 - i)}
+	}
+	mgr.AddRegistry(&mockRegistry{
+		name:          "test",
+		searchResults: results,
+	})
+
+	got, err := mgr.SearchAll(context.Background(), "test", 5)
+	assert.NoError(t, err)
+	assert.Len(t, got, 5)
+	// Top scores first
+	assert.Equal(t, "skill-0", got[0].Slug)
+}
+
+func TestRegistryManagerSearchAllTimeout(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Millisecond)
+	defer cancel()
+
+	time.Sleep(5 * time.Millisecond) // Let context expire.
+
+	mgr := NewRegistryManager()
+	mgr.AddRegistry(&mockRegistry{
+		name:      "slow",
+		searchErr: fmt.Errorf("context deadline exceeded"),
+	})
+
+	_, err := mgr.SearchAll(ctx, "test", 5)
+	assert.Error(t, err)
+}
+
+func TestSortByScoreDesc(t *testing.T) {
+	results := []SearchResult{
+		{Slug: "c", Score: 0.3},
+		{Slug: "a", Score: 0.9},
+		{Slug: "b", Score: 0.5},
+	}
+	sortByScoreDesc(results)
+	assert.Equal(t, "a", results[0].Slug)
+	assert.Equal(t, "b", results[1].Slug)
+	assert.Equal(t, "c", results[2].Slug)
+}
+
+func TestIsSafeSlug(t *testing.T) {
+	assert.NoError(t, utils.ValidateSkillIdentifier("github"))
+	assert.NoError(t, utils.ValidateSkillIdentifier("docker-compose"))
+	assert.Error(t, utils.ValidateSkillIdentifier(""))
+	assert.Error(t, utils.ValidateSkillIdentifier("../etc/passwd"))
+	assert.Error(t, utils.ValidateSkillIdentifier("path/traversal"))
+	assert.Error(t, utils.ValidateSkillIdentifier("path\\traversal"))
+}
--- a/pkg/skills/search_cache.go
+++ b/pkg/skills/search_cache.go
@ -0,0 +1,229 @@
+package skills
+
+import (
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// SearchCache provides lightweight caching for search results.
+// It uses trigram-based similarity to match similar queries to cached results,
+// avoiding redundant API calls. Thread-safe for concurrent access.
+type SearchCache struct {
+	mu         sync.RWMutex
+	entries    map[string]*cacheEntry
+	order      []string // LRU order: oldest first.
+	maxEntries int
+	ttl        time.Duration
+}
+
+type cacheEntry struct {
+	query     string
+	trigrams  []uint32
+	results   []SearchResult
+	createdAt time.Time
+}
+
+// similarityThreshold is the minimum trigram Jaccard similarity for a cache hit.
+const similarityThreshold = 0.7
+
+// NewSearchCache creates a new search cache.
+// maxEntries is the maximum number of cached queries (excess evicts LRU).
+// ttl is how long each entry lives before expiration.
+func NewSearchCache(maxEntries int, ttl time.Duration) *SearchCache {
+	if maxEntries <= 0 {
+		maxEntries = 50
+	}
+	if ttl <= 0 {
+		ttl = 5 * time.Minute
+	}
+	return &SearchCache{
+		entries:    make(map[string]*cacheEntry),
+		order:      make([]string, 0),
+		maxEntries: maxEntries,
+		ttl:        ttl,
+	}
+}
+
+// Get looks up results for a query. Returns cached results and true if found
+// (either exact or similar match above threshold). Returns nil, false on miss.
+func (sc *SearchCache) Get(query string) ([]SearchResult, bool) {
+	normalized := normalizeQuery(query)
+	if normalized == "" {
+		return nil, false
+	}
+
+	sc.mu.Lock()
+	defer sc.mu.Unlock()
+
+	// Exact match first.
+	if entry, ok := sc.entries[normalized]; ok {
+		if time.Since(entry.createdAt) < sc.ttl {
+			sc.moveToEndLocked(normalized)
+			return copyResults(entry.results), true
+		}
+	}
+
+	// Similarity match.
+	queryTrigrams := buildTrigrams(normalized)
+	var bestEntry *cacheEntry
+	var bestSim float64
+
+	for _, entry := range sc.entries {
+		if time.Since(entry.createdAt) >= sc.ttl {
+			continue // Skip expired.
+		}
+		sim := jaccardSimilarity(queryTrigrams, entry.trigrams)
+		if sim > bestSim {
+			bestSim = sim
+			bestEntry = entry
+		}
+	}
+
+	if bestSim >= similarityThreshold && bestEntry != nil {
+		sc.moveToEndLocked(bestEntry.query)
+		return copyResults(bestEntry.results), true
+	}
+
+	return nil, false
+}
+
+// Put stores results for a query. Evicts the oldest entry if at capacity.
+func (sc *SearchCache) Put(query string, results []SearchResult) {
+	normalized := normalizeQuery(query)
+	if normalized == "" {
+		return
+	}
+
+	sc.mu.Lock()
+	defer sc.mu.Unlock()
+
+	// Evict expired entries first.
+	sc.evictExpiredLocked()
+
+	// If already exists, update.
+	if _, ok := sc.entries[normalized]; ok {
+		sc.entries[normalized] = &cacheEntry{
+			query:     normalized,
+			trigrams:  buildTrigrams(normalized),
+			results:   copyResults(results),
+			createdAt: time.Now(),
+		}
+		// Move to end of LRU order.
+		sc.moveToEndLocked(normalized)
+		return
+	}
+
+	// Evict LRU if at capacity.
+	for len(sc.entries) >= sc.maxEntries && len(sc.order) > 0 {
+		oldest := sc.order[0]
+		sc.order = sc.order[1:]
+		delete(sc.entries, oldest)
+	}
+
+	// Insert new entry.
+	sc.entries[normalized] = &cacheEntry{
+		query:     normalized,
+		trigrams:  buildTrigrams(normalized),
+		results:   copyResults(results),
+		createdAt: time.Now(),
+	}
+	sc.order = append(sc.order, normalized)
+}
+
+// Len returns the number of entries (for testing).
+func (sc *SearchCache) Len() int {
+	sc.mu.RLock()
+	defer sc.mu.RUnlock()
+	return len(sc.entries)
+}
+
+// --- internal ---
+
+func (sc *SearchCache) evictExpiredLocked() {
+	now := time.Now()
+	newOrder := make([]string, 0, len(sc.order))
+	for _, key := range sc.order {
+		entry, ok := sc.entries[key]
+		if !ok || now.Sub(entry.createdAt) >= sc.ttl {
+			delete(sc.entries, key)
+			continue
+		}
+		newOrder = append(newOrder, key)
+	}
+	sc.order = newOrder
+}
+
+func (sc *SearchCache) moveToEndLocked(key string) {
+	for i, k := range sc.order {
+		if k == key {
+			sc.order = append(sc.order[:i], sc.order[i+1:]...)
+			break
+		}
+	}
+	sc.order = append(sc.order, key)
+}
+
+func normalizeQuery(q string) string {
+	return strings.ToLower(strings.TrimSpace(q))
+}
+
+// buildTrigrams generates hash of trigrams from a string.
+// Example: "hello" → {"hel", "ell", "llo"}
+// "hel" -> 0x0068656c -> 4 bytes; compared to 16 bytes of a string
+func buildTrigrams(s string) []uint32 {
+	if len(s) < 3 {
+		return nil
+	}
+
+	trigrams := make([]uint32, 0, len(s)-2)
+	for i := 0; i <= len(s)-3; i++ {
+		trigrams = append(trigrams, uint32(s[i])<<16|uint32(s[i+1])<<8|uint32(s[i+2]))
+	}
+
+	// Sort and Deduplication
+	sort.Slice(trigrams, func(i, j int) bool { return trigrams[i] < trigrams[j] })
+	n := 1
+	for i := 1; i < len(trigrams); i++ {
+		if trigrams[i] != trigrams[i-1] {
+			trigrams[n] = trigrams[i]
+			n++
+		}
+	}
+
+	return trigrams[:n]
+}
+
+// jaccardSimilarity computes |A ∩ B| / |A ∪ B|.
+func jaccardSimilarity(a, b []uint32) float64 {
+	if len(a) == 0 && len(b) == 0 {
+		return 1
+	}
+	i, j := 0, 0
+	intersection := 0
+
+	for i < len(a) && j < len(b) {
+		if a[i] == b[j] {
+			intersection++
+			i++
+			j++
+		} else if a[i] < b[j] {
+			i++
+		} else {
+			j++
+		}
+	}
+
+	union := len(a) + len(b) - intersection
+	return float64(intersection) / float64(union)
+}
+
+func copyResults(results []SearchResult) []SearchResult {
+	if results == nil {
+		return nil
+	}
+	cp := make([]SearchResult, len(results))
+	copy(cp, results)
+	return cp
+}
--- a/pkg/skills/search_cache_test.go
+++ b/pkg/skills/search_cache_test.go
@ -0,0 +1,200 @@
+package skills
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSearchCacheExactHit(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	results := []SearchResult{
+		{Slug: "github", Score: 0.9, RegistryName: "clawhub"},
+		{Slug: "docker", Score: 0.7, RegistryName: "clawhub"},
+	}
+	cache.Put("github integration", results)
+
+	got, hit := cache.Get("github integration")
+	assert.True(t, hit)
+	assert.Len(t, got, 2)
+	assert.Equal(t, "github", got[0].Slug)
+}
+
+func TestSearchCacheExactHitCaseInsensitive(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	results := []SearchResult{{Slug: "github", Score: 0.9}}
+	cache.Put("GitHub Integration", results)
+
+	got, hit := cache.Get("github integration")
+	assert.True(t, hit)
+	assert.Len(t, got, 1)
+}
+
+func TestSearchCacheSimilarHit(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	results := []SearchResult{{Slug: "github", Score: 0.9}}
+	cache.Put("github integration tool", results)
+
+	// "github integration" is very similar to "github integration tool"
+	got, hit := cache.Get("github integration")
+	assert.True(t, hit)
+	assert.Len(t, got, 1)
+}
+
+func TestSearchCacheDissimilarMiss(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	results := []SearchResult{{Slug: "github", Score: 0.9}}
+	cache.Put("github integration", results)
+
+	// Completely unrelated query
+	_, hit := cache.Get("database management")
+	assert.False(t, hit)
+}
+
+func TestSearchCacheTTLExpiration(t *testing.T) {
+	cache := NewSearchCache(10, 50*time.Millisecond)
+
+	results := []SearchResult{{Slug: "github", Score: 0.9}}
+	cache.Put("github integration", results)
+
+	// Immediately should hit
+	_, hit := cache.Get("github integration")
+	assert.True(t, hit)
+
+	// Wait for expiration
+	time.Sleep(100 * time.Millisecond)
+
+	_, hit = cache.Get("github integration")
+	assert.False(t, hit)
+}
+
+func TestSearchCacheLRUEviction(t *testing.T) {
+	cache := NewSearchCache(3, 5*time.Minute)
+
+	cache.Put("query-1", []SearchResult{{Slug: "a"}})
+	cache.Put("query-2", []SearchResult{{Slug: "b"}})
+	cache.Put("query-3", []SearchResult{{Slug: "c"}})
+
+	assert.Equal(t, 3, cache.Len())
+
+	// Adding a 4th should evict query-1 (oldest)
+	cache.Put("query-4", []SearchResult{{Slug: "d"}})
+	assert.Equal(t, 3, cache.Len())
+
+	_, hit := cache.Get("query-1")
+	assert.False(t, hit, "oldest entry should be evicted")
+
+	got, hit := cache.Get("query-4")
+	assert.True(t, hit)
+	assert.Equal(t, "d", got[0].Slug)
+}
+
+func TestSearchCacheEmptyQuery(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	_, hit := cache.Get("")
+	assert.False(t, hit)
+
+	_, hit = cache.Get("   ")
+	assert.False(t, hit)
+}
+
+func TestSearchCacheResultsCopied(t *testing.T) {
+	cache := NewSearchCache(10, 5*time.Minute)
+
+	original := []SearchResult{{Slug: "github", Score: 0.9}}
+	cache.Put("test", original)
+
+	// Mutate original after putting
+	original[0].Slug = "mutated"
+
+	got, hit := cache.Get("test")
+	assert.True(t, hit)
+	assert.Equal(t, "github", got[0].Slug, "cache should hold a copy, not a reference")
+}
+
+func TestBuildTrigrams(t *testing.T) {
+	trigrams := buildTrigrams("hello")
+	assert.Contains(t, trigrams, uint32('h')<<16|uint32('e')<<8|uint32('l'))
+	assert.Contains(t, trigrams, uint32('e')<<16|uint32('l')<<8|uint32('l'))
+	assert.Contains(t, trigrams, uint32('l')<<16|uint32('l')<<8|uint32('o'))
+	assert.Len(t, trigrams, 3)
+}
+
+func TestJaccardSimilarity(t *testing.T) {
+	a := buildTrigrams("github integration")
+	b := buildTrigrams("github integration tool")
+
+	sim := jaccardSimilarity(a, b)
+	assert.Greater(t, sim, 0.5, "similar strings should have high sim")
+
+	c := buildTrigrams("completely different query about databases")
+	sim2 := jaccardSimilarity(a, c)
+	assert.Less(t, sim2, 0.3, "dissimilar strings should have low sim")
+}
+
+func TestJaccardSimilarityEdgeCases(t *testing.T) {
+	empty := buildTrigrams("")
+	nonempty := buildTrigrams("hello")
+
+	assert.Equal(t, 1.0, jaccardSimilarity(empty, empty))
+	assert.Equal(t, 0.0, jaccardSimilarity(empty, nonempty))
+	assert.Equal(t, 0.0, jaccardSimilarity(nonempty, empty))
+}
+
+func TestSearchCacheConcurrency(t *testing.T) {
+	cache := NewSearchCache(50, 5*time.Minute)
+	done := make(chan struct{})
+
+	// Concurrent writes
+	go func() {
+		for i := 0; i < 100; i++ {
+			cache.Put("query-write-"+string(rune('a'+i%26)), []SearchResult{{Slug: "x"}})
+		}
+		done <- struct{}{}
+	}()
+
+	// Concurrent reads
+	go func() {
+		for i := 0; i < 100; i++ {
+			cache.Get("query-write-a")
+		}
+		done <- struct{}{}
+	}()
+
+	<-done
+}
+
+func TestSearchCacheLRUUpdateOnGet(t *testing.T) {
+	// Capacity 3
+	cache := NewSearchCache(3, time.Hour)
+
+	// Fill cache: query-A, query-B, query-C
+	// Use longer strings to ensure trigrams are generated and avoid false positive similarity
+	cache.Put("query-A", []SearchResult{{Slug: "A"}})
+	cache.Put("query-B", []SearchResult{{Slug: "B"}})
+	cache.Put("query-C", []SearchResult{{Slug: "C"}})
+
+	// Access query-A (should make it most recently used)
+	if _, found := cache.Get("query-A"); !found {
+		t.Fatal("query-A should be in cache")
+	}
+
+	// Add query-D. Should evict query-B (LRU) instead of query-A (which was refreshed)
+	cache.Put("query-D", []SearchResult{{Slug: "D"}})
+
+	// Check if query-A is still there
+	if _, found := cache.Get("query-A"); !found {
+		t.Fatalf("query-A was evicted! valid LRU should have kept query-A and evicted query-B.")
+	}
+
+	// Check if query-B is evicted
+	if _, found := cache.Get("query-B"); found {
+		t.Fatal("query-B should have been evicted")
+	}
+}
--- a/pkg/tools/skills_install.go
+++ b/pkg/tools/skills_install.go
@ -0,0 +1,199 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+// InstallSkillTool allows the LLM agent to install skills from registries.
+// It shares the same RegistryManager that FindSkillsTool uses,
+// so all registries configured in config are available for installation.
+type InstallSkillTool struct {
+	registryMgr *skills.RegistryManager
+	workspace   string
+	mu          sync.Mutex
+}
+
+// NewInstallSkillTool creates a new InstallSkillTool.
+// registryMgr is the shared registry manager (same instance as FindSkillsTool).
+// workspace is the root workspace directory; skills install to {workspace}/skills/{slug}/.
+func NewInstallSkillTool(registryMgr *skills.RegistryManager, workspace string) *InstallSkillTool {
+	return &InstallSkillTool{
+		registryMgr: registryMgr,
+		workspace:   workspace,
+		mu:          sync.Mutex{},
+	}
+}
+
+func (t *InstallSkillTool) Name() string {
+	return "install_skill"
+}
+
+func (t *InstallSkillTool) Description() string {
+	return "Install a skill from a registry by slug. Downloads and extracts the skill into the workspace. Use find_skills first to discover available skills."
+}
+
+func (t *InstallSkillTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"slug": map[string]interface{}{
+				"type":        "string",
+				"description": "The unique slug of the skill to install (e.g., 'github', 'docker-compose')",
+			},
+			"version": map[string]interface{}{
+				"type":        "string",
+				"description": "Specific version to install (optional, defaults to latest)",
+			},
+			"registry": map[string]interface{}{
+				"type":        "string",
+				"description": "Registry to install from (required, e.g., 'clawhub')",
+			},
+			"force": map[string]interface{}{
+				"type":        "boolean",
+				"description": "Force reinstall if skill already exists (default false)",
+			},
+		},
+		"required": []string{"slug", "registry"},
+	}
+}
+
+func (t *InstallSkillTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
+	// Install lock to prevent concurrent directory operations.
+	// Ideally this should be done at a `slug` level, currently, its at a `workspace` level.
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	// Validate slug
+	slug, _ := args["slug"].(string)
+	if err := utils.ValidateSkillIdentifier(slug); err != nil {
+		return ErrorResult(fmt.Sprintf("invalid slug %q: error: %s", slug, err.Error()))
+	}
+
+	// Validate registry
+	registryName, _ := args["registry"].(string)
+	if err := utils.ValidateSkillIdentifier(registryName); err != nil {
+		return ErrorResult(fmt.Sprintf("invalid registry %q: error: %s", registryName, err.Error()))
+	}
+
+	version, _ := args["version"].(string)
+	force, _ := args["force"].(bool)
+
+	// Check if already installed.
+	skillsDir := filepath.Join(t.workspace, "skills")
+	targetDir := filepath.Join(skillsDir, slug)
+
+	if !force {
+		if _, err := os.Stat(targetDir); err == nil {
+			return ErrorResult(fmt.Sprintf("skill %q already installed at %s. Use force=true to reinstall.", slug, targetDir))
+		}
+	} else {
+		// Force: remove existing if present.
+		os.RemoveAll(targetDir)
+	}
+
+	// Resolve which registry to use.
+	registry := t.registryMgr.GetRegistry(registryName)
+	if registry == nil {
+		return ErrorResult(fmt.Sprintf("registry %q not found", registryName))
+	}
+
+	// Ensure skills directory exists.
+	if err := os.MkdirAll(skillsDir, 0755); err != nil {
+		return ErrorResult(fmt.Sprintf("failed to create skills directory: %v", err))
+	}
+
+	// Download and install (handles metadata, version resolution, extraction).
+	result, err := registry.DownloadAndInstall(ctx, slug, version, targetDir)
+	if err != nil {
+		// Clean up partial install.
+		rmErr := os.RemoveAll(targetDir)
+		if rmErr != nil {
+			logger.ErrorCF("tool", "Failed to remove partial install",
+				map[string]interface{}{
+					"tool":       "install_skill",
+					"target_dir": targetDir,
+					"error":      rmErr.Error(),
+				})
+		}
+		return ErrorResult(fmt.Sprintf("failed to install %q: %v", slug, err))
+	}
+
+	// Moderation: block malware.
+	if result.IsMalwareBlocked {
+		rmErr := os.RemoveAll(targetDir)
+		if rmErr != nil {
+			logger.ErrorCF("tool", "Failed to remove partial install",
+				map[string]interface{}{
+					"tool":       "install_skill",
+					"target_dir": targetDir,
+					"error":      rmErr.Error(),
+				})
+		}
+		return ErrorResult(fmt.Sprintf("skill %q is flagged as malicious and cannot be installed", slug))
+	}
+
+	// Write origin metadata.
+	if err := writeOriginMeta(targetDir, registry.Name(), slug, result.Version); err != nil {
+		logger.ErrorCF("tool", "Failed to write origin metadata",
+			map[string]interface{}{
+				"tool":     "install_skill",
+				"error":    err.Error(),
+				"target":   targetDir,
+				"registry": registry.Name(),
+				"slug":     slug,
+				"version":  result.Version,
+			})
+		_ = err
+	}
+
+	// Build result with moderation warning if suspicious.
+	var output string
+	if result.IsSuspicious {
+		output = fmt.Sprintf("⚠️ Warning: skill %q is flagged as suspicious (may contain risky patterns).\n\n", slug)
+	}
+	output += fmt.Sprintf("Successfully installed skill %q v%s from %s registry.\nLocation: %s\n",
+		slug, result.Version, registry.Name(), targetDir)
+
+	if result.Summary != "" {
+		output += fmt.Sprintf("Description: %s\n", result.Summary)
+	}
+	output += "\nThe skill is now available and can be loaded in the current session."
+
+	return SilentResult(output)
+}
+
+// originMeta tracks which registry a skill was installed from.
+type originMeta struct {
+	Version          int    `json:"version"`
+	Registry         string `json:"registry"`
+	Slug             string `json:"slug"`
+	InstalledVersion string `json:"installed_version"`
+	InstalledAt      int64  `json:"installed_at"`
+}
+
+func writeOriginMeta(targetDir, registryName, slug, version string) error {
+	meta := originMeta{
+		Version:          1,
+		Registry:         registryName,
+		Slug:             slug,
+		InstalledVersion: version,
+		InstalledAt:      time.Now().UnixMilli(),
+	}
+
+	data, err := json.MarshalIndent(meta, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(filepath.Join(targetDir, ".skill-origin.json"), data, 0644)
+}
--- a/pkg/tools/skills_install_test.go
+++ b/pkg/tools/skills_install_test.go
@ -0,0 +1,103 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestInstallSkillToolName(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	assert.Equal(t, "install_skill", tool.Name())
+}
+
+func TestInstallSkillToolMissingSlug(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	result := tool.Execute(context.Background(), map[string]interface{}{})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "identifier is required and must be a non-empty string")
+}
+
+func TestInstallSkillToolEmptySlug(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"slug": "   ",
+	})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "identifier is required and must be a non-empty string")
+}
+
+func TestInstallSkillToolUnsafeSlug(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+
+	cases := []string{
+		"../etc/passwd",
+		"path/traversal",
+		"path\\traversal",
+	}
+
+	for _, slug := range cases {
+		result := tool.Execute(context.Background(), map[string]interface{}{
+			"slug": slug,
+		})
+		assert.True(t, result.IsError, "slug %q should be rejected", slug)
+		assert.Contains(t, result.ForLLM, "invalid slug")
+	}
+}
+
+func TestInstallSkillToolAlreadyExists(t *testing.T) {
+	workspace := t.TempDir()
+	skillDir := filepath.Join(workspace, "skills", "existing-skill")
+	require.NoError(t, os.MkdirAll(skillDir, 0755))
+
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace)
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"slug":     "existing-skill",
+		"registry": "clawhub",
+	})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "already installed")
+}
+
+func TestInstallSkillToolRegistryNotFound(t *testing.T) {
+	workspace := t.TempDir()
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), workspace)
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"slug":     "some-skill",
+		"registry": "nonexistent",
+	})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "registry")
+	assert.Contains(t, result.ForLLM, "not found")
+}
+
+func TestInstallSkillToolParameters(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	params := tool.Parameters()
+
+	props, ok := params["properties"].(map[string]interface{})
+	assert.True(t, ok)
+	assert.Contains(t, props, "slug")
+	assert.Contains(t, props, "version")
+	assert.Contains(t, props, "registry")
+	assert.Contains(t, props, "force")
+
+	required, ok := params["required"].([]string)
+	assert.True(t, ok)
+	assert.Contains(t, required, "slug")
+	assert.Contains(t, required, "registry")
+}
+
+func TestInstallSkillToolMissingRegistry(t *testing.T) {
+	tool := NewInstallSkillTool(skills.NewRegistryManager(), t.TempDir())
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"slug": "some-skill",
+	})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "invalid registry")
+}
--- a/pkg/tools/skills_search.go
+++ b/pkg/tools/skills_search.go
@ -0,0 +1,119 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+// FindSkillsTool allows the LLM agent to search for installable skills from registries.
+type FindSkillsTool struct {
+	registryMgr *skills.RegistryManager
+	cache       *skills.SearchCache
+}
+
+// NewFindSkillsTool creates a new FindSkillsTool.
+// registryMgr is the shared registry manager (built from config in createToolRegistry).
+// cache is the search cache for deduplicating similar queries.
+func NewFindSkillsTool(registryMgr *skills.RegistryManager, cache *skills.SearchCache) *FindSkillsTool {
+	return &FindSkillsTool{
+		registryMgr: registryMgr,
+		cache:       cache,
+	}
+}
+
+func (t *FindSkillsTool) Name() string {
+	return "find_skills"
+}
+
+func (t *FindSkillsTool) Description() string {
+	return "Search for installable skills from skill registries. Returns skill slugs, descriptions, versions, and relevance scores. Use this to discover skills before installing them with install_skill."
+}
+
+func (t *FindSkillsTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"query": map[string]interface{}{
+				"type":        "string",
+				"description": "Search query describing the desired skill capability (e.g., 'github integration', 'database management')",
+			},
+			"limit": map[string]interface{}{
+				"type":        "integer",
+				"description": "Maximum number of results to return (1-20, default 5)",
+				"minimum":     1.0,
+				"maximum":     20.0,
+			},
+		},
+		"required": []string{"query"},
+	}
+}
+
+func (t *FindSkillsTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
+	query, ok := args["query"].(string)
+	query = strings.ToLower(strings.TrimSpace(query))
+	if !ok || query == "" {
+		return ErrorResult("query is required and must be a non-empty string")
+	}
+
+	limit := 5
+	if l, ok := args["limit"].(float64); ok {
+		li := int(l)
+		if li >= 1 && li <= 20 {
+			limit = li
+		}
+	}
+
+	// Check cache first.
+	if t.cache != nil {
+		if cached, hit := t.cache.Get(query); hit {
+			return SilentResult(formatSearchResults(query, cached, true))
+		}
+	}
+
+	// Search all registries.
+	results, err := t.registryMgr.SearchAll(ctx, query, limit)
+	if err != nil {
+		return ErrorResult(fmt.Sprintf("skill search failed: %v", err))
+	}
+
+	// Cache the results.
+	if t.cache != nil && len(results) > 0 {
+		t.cache.Put(query, results)
+	}
+
+	return SilentResult(formatSearchResults(query, results, false))
+}
+
+func formatSearchResults(query string, results []skills.SearchResult, cached bool) string {
+	if len(results) == 0 {
+		return fmt.Sprintf("No skills found for query: %q", query)
+	}
+
+	var sb strings.Builder
+	source := ""
+	if cached {
+		source = " (cached)"
+	}
+	sb.WriteString(fmt.Sprintf("Found %d skills for %q%s:\n\n", len(results), query, source))
+
+	for i, r := range results {
+		sb.WriteString(fmt.Sprintf("%d. **%s**", i+1, r.Slug))
+		if r.Version != "" {
+			sb.WriteString(fmt.Sprintf(" v%s", r.Version))
+		}
+		sb.WriteString(fmt.Sprintf("  (score: %.3f, registry: %s)\n", r.Score, r.RegistryName))
+		if r.DisplayName != "" && r.DisplayName != r.Slug {
+			sb.WriteString(fmt.Sprintf("   Name: %s\n", r.DisplayName))
+		}
+		if r.Summary != "" {
+			sb.WriteString(fmt.Sprintf("   %s\n", r.Summary))
+		}
+		sb.WriteString("\n")
+	}
+
+	sb.WriteString("Use install_skill with the slug to install a skill.")
+	return sb.String()
+}
--- a/pkg/tools/skills_search_test.go
+++ b/pkg/tools/skills_search_test.go
@ -0,0 +1,82 @@
+package tools
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestFindSkillsToolName(t *testing.T) {
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	assert.Equal(t, "find_skills", tool.Name())
+}
+
+func TestFindSkillsToolMissingQuery(t *testing.T) {
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	result := tool.Execute(context.Background(), map[string]interface{}{})
+	assert.True(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "query is required")
+}
+
+func TestFindSkillsToolEmptyQuery(t *testing.T) {
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"query": "   ",
+	})
+	assert.True(t, result.IsError)
+}
+
+func TestFindSkillsToolCacheHit(t *testing.T) {
+	cache := skills.NewSearchCache(10, 5*60*1000*1000*1000) // 5 min
+	cache.Put("github", []skills.SearchResult{
+		{Slug: "github", Score: 0.9, RegistryName: "clawhub"},
+	})
+
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), cache)
+	result := tool.Execute(context.Background(), map[string]interface{}{
+		"query": "github",
+	})
+
+	assert.False(t, result.IsError)
+	assert.Contains(t, result.ForLLM, "github")
+	assert.Contains(t, result.ForLLM, "cached")
+}
+
+func TestFindSkillsToolParameters(t *testing.T) {
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	params := tool.Parameters()
+
+	props, ok := params["properties"].(map[string]interface{})
+	assert.True(t, ok)
+	assert.Contains(t, props, "query")
+	assert.Contains(t, props, "limit")
+
+	required, ok := params["required"].([]string)
+	assert.True(t, ok)
+	assert.Contains(t, required, "query")
+}
+
+func TestFindSkillsToolDescription(t *testing.T) {
+	tool := NewFindSkillsTool(skills.NewRegistryManager(), nil)
+	assert.NotEmpty(t, tool.Description())
+	assert.Contains(t, tool.Description(), "skill")
+}
+
+func TestFormatSearchResultsEmpty(t *testing.T) {
+	result := formatSearchResults("test query", nil, false)
+	assert.Contains(t, result, "No skills found")
+}
+
+func TestFormatSearchResultsWithData(t *testing.T) {
+	results := []skills.SearchResult{
+		{Slug: "github", Score: 0.95, DisplayName: "GitHub", Summary: "GitHub API integration", Version: "1.0.0", RegistryName: "clawhub"},
+	}
+	output := formatSearchResults("github", results, false)
+	assert.Contains(t, output, "github")
+	assert.Contains(t, output, "v1.0.0")
+	assert.Contains(t, output, "0.950")
+	assert.Contains(t, output, "clawhub")
+	assert.Contains(t, output, "install_skill")
+}
--- a/pkg/utils/download.go
+++ b/pkg/utils/download.go
@ -0,0 +1,93 @@
+package utils
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// DownloadToFile streams an HTTP response body to a temporary file in small
+// chunks (~32KB), keeping peak memory usage constant regardless of file size.
+//
+// Parameters:
+//   - ctx:      context for cancellation/timeout
+//   - client:   HTTP client to use (caller controls timeouts, transport, etc.)
+//   - req:      fully prepared *http.Request (method, URL, headers, etc.)
+//   - maxBytes: maximum bytes to download; 0 means no limit
+//
+// Returns the path to the temporary file. The caller is responsible for
+// removing it when done (defer os.Remove(path)).
+//
+// On any error the temp file is cleaned up automatically.
+func DownloadToFile(ctx context.Context, client *http.Client, req *http.Request, maxBytes int64) (string, error) {
+	// Attach context.
+	req = req.WithContext(ctx)
+
+	logger.DebugCF("download", "Starting download", map[string]interface{}{
+		"url":       req.URL.String(),
+		"max_bytes": maxBytes,
+	})
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		// Read a small amount for the error message.
+		errBody := make([]byte, 512)
+		n, _ := io.ReadFull(resp.Body, errBody)
+		return "", fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(errBody[:n]))
+	}
+
+	// Create temp file.
+	tmpFile, err := os.CreateTemp("", "picoclaw-dl-*")
+	if err != nil {
+		return "", fmt.Errorf("failed to create temp file: %w", err)
+	}
+	tmpPath := tmpFile.Name()
+
+	logger.DebugCF("download", "Streaming to temp file", map[string]interface{}{
+		"path": tmpPath,
+	})
+
+	// Cleanup helper — removes the temp file on any error.
+	cleanup := func() {
+		_ = tmpFile.Close()
+		_ = os.Remove(tmpPath)
+	}
+
+	// Optionally limit the download size.
+	var src io.Reader = resp.Body
+	if maxBytes > 0 {
+		src = io.LimitReader(resp.Body, maxBytes+1) // +1 to detect overflow
+	}
+
+	written, err := io.Copy(tmpFile, src)
+	if err != nil {
+		cleanup()
+		return "", fmt.Errorf("download write failed: %w", err)
+	}
+
+	if maxBytes > 0 && written > maxBytes {
+		cleanup()
+		return "", fmt.Errorf("download too large: %d bytes (max %d)", written, maxBytes)
+	}
+
+	if err := tmpFile.Close(); err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	logger.DebugCF("download", "Download complete", map[string]interface{}{
+		"path":          tmpPath,
+		"bytes_written": written,
+	})
+
+	return tmpPath, nil
+}
--- a/pkg/utils/skills.go
+++ b/pkg/utils/skills.go
@ -0,0 +1,19 @@
+package utils
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ValidateSkillIdentifier validates that the given skill identifier (slug or registry name) is non-empty
+// and does not contain path separators ("/", "\\") or ".." for security.
+func ValidateSkillIdentifier(identifier string) error {
+	trimmed := strings.TrimSpace(identifier)
+	if trimmed == "" {
+		return fmt.Errorf("identifier is required and must be a non-empty string")
+	}
+	if strings.ContainsAny(trimmed, "/\\") || strings.Contains(trimmed, "..") {
+		return fmt.Errorf("identifier must not contain path separators or '..' to prevent directory traversal")
+	}
+	return nil
+}
--- a/pkg/utils/string.go
+++ b/pkg/utils/string.go
@ -14,3 +14,12 @@ func Truncate(s string, maxLen int) string {
 	}
 	return string(runes[:maxLen-3]) + "..."
 }
+
+// DerefStr dereferences a pointer to a string and
+// returns the value or a fallback if the pointer is nil.
+func DerefStr(s *string, fallback string) string {
+	if s == nil {
+		return fallback
+	}
+	return *s
+}
--- a/pkg/utils/zip.go
+++ b/pkg/utils/zip.go
@ -0,0 +1,120 @@
+package utils
+
+import (
+	"archive/zip"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// ExtractZipFile extracts a ZIP archive from disk to targetDir.
+// It reads entries one at a time from disk, keeping memory usage minimal.
+//
+// Security: rejects path traversal attempts and symlinks.
+func ExtractZipFile(zipPath string, targetDir string) error {
+	reader, err := zip.OpenReader(zipPath)
+	if err != nil {
+		return fmt.Errorf("invalid ZIP: %w", err)
+	}
+	defer reader.Close()
+
+	logger.DebugCF("zip", "Extracting ZIP", map[string]interface{}{
+		"zip_path":   zipPath,
+		"target_dir": targetDir,
+		"entries":    len(reader.File),
+	})
+
+	if err := os.MkdirAll(targetDir, 0755); err != nil {
+		return fmt.Errorf("failed to create target dir: %w", err)
+	}
+
+	for _, f := range reader.File {
+		// Path traversal protection.
+		cleanName := filepath.Clean(f.Name)
+		if strings.HasPrefix(cleanName, "..") || filepath.IsAbs(cleanName) {
+			return fmt.Errorf("zip entry has unsafe path: %q", f.Name)
+		}
+
+		destPath := filepath.Join(targetDir, cleanName)
+
+		// Double-check the resolved path is within target directory (defense-in-depth).
+		targetDirClean := filepath.Clean(targetDir)
+		if !strings.HasPrefix(filepath.Clean(destPath), targetDirClean+string(filepath.Separator)) && filepath.Clean(destPath) != targetDirClean {
+			return fmt.Errorf("zip entry escapes target dir: %q", f.Name)
+		}
+
+		mode := f.FileInfo().Mode()
+
+		// Reject any symlink.
+		if mode&os.ModeSymlink != 0 {
+			return fmt.Errorf("zip contains symlink %q; symlinks are not allowed", f.Name)
+		}
+
+		if f.FileInfo().IsDir() {
+			if err := os.MkdirAll(destPath, 0755); err != nil {
+				return err
+			}
+			continue
+		}
+
+		// Ensure parent directory exists.
+		if err := os.MkdirAll(filepath.Dir(destPath), 0755); err != nil {
+			return err
+		}
+
+		if err := extractSingleFile(f, destPath); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// extractSingleFile extracts one zip.File entry to destPath, with a size check.
+func extractSingleFile(f *zip.File, destPath string) error {
+	const maxFileSize = 5 * 1024 * 1024 // 5MB, adjust as appropriate
+
+	// Check the uncompressed size from the header, if available.
+	if f.UncompressedSize64 > maxFileSize {
+		return fmt.Errorf("zip entry %q is too large (%d bytes)", f.Name, f.UncompressedSize64)
+	}
+
+	rc, err := f.Open()
+	if err != nil {
+		return fmt.Errorf("failed to open zip entry %q: %w", f.Name, err)
+	}
+	defer rc.Close()
+
+	outFile, err := os.Create(destPath)
+	if err != nil {
+		return fmt.Errorf("failed to create file %q: %w", destPath, err)
+	}
+	// We don't return the close error via return, since it's not a named error return.
+	// Instead, we log to stderr and remove the partially written file as defensive cleanup.
+	defer func() {
+		if cerr := outFile.Close(); cerr != nil {
+			_ = os.Remove(destPath)
+			logger.ErrorCF("zip", "Failed to close file", map[string]interface{}{
+				"dest_path": destPath,
+				"error":     cerr.Error(),
+			})
+		}
+	}()
+
+	// Streamed size check: prevent overruns and malicious/corrupt headers.
+	written, err := io.CopyN(outFile, rc, maxFileSize+1)
+	if err != nil && err != io.EOF {
+		_ = os.Remove(destPath)
+		return fmt.Errorf("failed to extract %q: %w", f.Name, err)
+	}
+	if written > maxFileSize {
+		_ = os.Remove(destPath)
+		return fmt.Errorf("zip entry %q exceeds max size (%d bytes)", f.Name, written)
+	}
+
+	return nil
+}