Merge upstream/main: deps, docs, and trivial changes (PR1)

Merge 126 upstream commits, resolving PR1-scope conflicts: - go.mod: adopt upstream dep versions (irc-go 0.6, go-sdk 1.4.1, net 0.52) - Makefile: maintain mipsle/netbsd skip (sqlite compat) - READMEs: integrate new language links (it, id) - pkg/tools/web.go: add Cloudflare challenge retry - pkg/tools/shell.go: whitespace-only merge - pkg/config/config.go: restore ToolFeedbackConfig, Deferred, etc. for upstream defaults.go compatibility - web/frontend/package.json: adopt upstream dep bumps Non-PR1 files kept as ours (deferred to PR2-4): - pkg/agent/{loop,instance}.go, pkg/bus/bus.go, pkg/channels/{manager,telegram}.go, pkg/providers/* Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 17:55:21 +09:00 · 2026-03-20 17:55:21 +09:00 · 7e74a3c328
commit 7e74a3c328
parent 72e3b09147 fe87376d6a
63 changed files with 4542 additions and 918 deletions
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@ -62,7 +62,7 @@ jobs:
        run: cd pkg/miniapp/frontend && bun install

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
@ -85,7 +85,7 @@ jobs:
        run: git tag "${{ steps.version.outputs.version }}"

      - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
        with:
          distribution: goreleaser
          version: ~> v2
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@ -74,7 +74,7 @@ jobs:
        run: corepack enable && corepack prepare pnpm@latest --activate

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4
@ -94,7 +94,7 @@ jobs:
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
        with:
          distribution: goreleaser
          version: ~> v2
--- a/README.fr.md
+++ b/README.fr.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [English](README.md) | **Français**
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)

 </div>

--- a/README.id.md
+++ b/README.id.md
@ -0,0 +1,249 @@
+<div align="center">
+  <img src="assets/logo.webp" alt="PicoClaw" width="512">
+
+  <h1>PicoClaw: Asisten AI Super Ringan berbasis Go</h1>
+
+  <h3>Perangkat Keras $10 · RAM <10MB · Boot <1 Detik · Ayo, Berangkat!</h3>
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [English](README.md) | **Bahasa Indonesia**
+
+</div>
+
+---
+
+> **PicoClaw** adalah proyek open-source independen yang diinisiasi oleh [Sipeed](https://sipeed.com). Ditulis sepenuhnya dalam **Go** — bukan fork dari OpenClaw, NanoBot, atau proyek lainnya.
+
+🦐 PicoClaw adalah asisten AI pribadi yang super ringan, terinspirasi dari [NanoBot](https://github.com/HKUDS/nanobot), ditulis ulang sepenuhnya dalam Go melalui proses "self-bootstrapping" — di mana AI Agent itu sendiri yang memandu seluruh migrasi arsitektur dan optimasi kode.
+
+⚡️ Berjalan di perangkat keras $10 dengan RAM <10MB: Hemat 99% memori dibanding OpenClaw dan 98% lebih murah dibanding Mac mini!
+
+<table align="center">
+  <tr align="center">
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/picoclaw_mem.gif" width="360" height="240">
+      </p>
+    </td>
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/licheervnano.png" width="400" height="240">
+      </p>
+    </td>
+  </tr>
+</table>
+
+> [!CAUTION]
+> **🚨 KEAMANAN & SALURAN RESMI**
+>
+> * **TANPA KRIPTO:** PicoClaw **TIDAK** memiliki token/koin resmi. Semua klaim di `pump.fun` atau platform trading lainnya adalah **PENIPUAN**.
+>
+> * **DOMAIN RESMI:** Satu-satunya website resmi adalah **[picoclaw.io](https://picoclaw.io)**, dan website perusahaan adalah **[sipeed.com](https://sipeed.com)**
+> * **Peringatan:** Banyak domain `.ai/.org/.com/.net/...` yang didaftarkan oleh pihak ketiga.
+> * **Peringatan:** PicoClaw masih dalam tahap pengembangan awal dan mungkin memiliki masalah keamanan jaringan yang belum teratasi. Jangan deploy ke lingkungan produksi sebelum rilis v1.0.
+> * **Catatan:** PicoClaw baru-baru ini menggabungkan banyak PR, yang mungkin mengakibatkan penggunaan memori lebih besar (10–20MB) pada versi terbaru. Kami berencana untuk memprioritaskan optimasi sumber daya segera setelah fitur saat ini mencapai kondisi stabil.
+
+## 📢 Berita
+
+2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental gateway hot-reload, gerbang keamanan cron, dan 2 perbaikan keamanan. PicoClaw kini di **25K ⭐**!
+
+2026-03-09 🎉 **v0.2.1 — Update terbesar!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, dan routing model.
+
+2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan launcher Web UI.
+
+2026-02-26 🎉 PicoClaw mencapai **20K bintang** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas diluncurkan.
+
+<details>
+<summary>Berita lama...</summary>
+
+2026-02-16 🎉 PicoClaw mencapai 12K bintang dalam satu minggu! Peran maintainer komunitas dan [roadmap](ROADMAP.md) resmi diposting.
+
+2026-02-13 🎉 PicoClaw mencapai 5000 bintang dalam 4 hari! Roadmap Proyek dan pengaturan Grup Pengembang sedang berjalan.
+
+2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. 🦐 PicoClaw, Ayo Berangkat!
+
+</details>
+
+## ✨ Fitur
+
+🪶 **Super Ringan**: Penggunaan memori <10MB — 99% lebih kecil dari fungsionalitas inti OpenClaw.*
+
+💰 **Biaya Minimal**: Cukup efisien untuk berjalan di perangkat keras $10 — 98% lebih murah dari Mac mini.
+
+⚡️ **Secepat Kilat**: Waktu startup 400X lebih cepat, boot dalam <1 detik bahkan di prosesor single core 0,6GHz.
+
+🌍 **Portabilitas Sejati**: Satu binary mandiri untuk RISC-V, ARM, MIPS, dan x86, Satu Klik Langsung Jalan!
+
+🤖 **AI-Bootstrapped**: Implementasi Go-native secara otonom — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop.
+
+🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas agent.
+
+👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke agent — encoding base64 otomatis untuk LLM multimodal.
+
+🧠 **Routing Cerdas**: Routing model berbasis aturan — kueri sederhana diarahkan ke model ringan, menghemat biaya API.
+
+_*Versi terbaru mungkin menggunakan 10–20MB karena penggabungan fitur yang cepat. Optimasi sumber daya direncanakan. Perbandingan startup berdasarkan benchmark prosesor single-core 0,8GHz (lihat tabel di bawah)._
+
+|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
+| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
+| **Bahasa**                    | TypeScript    | Python                   | **Go**                                    |
+| **RAM**                       | >1GB          | >100MB                   | **< 10MB***                               |
+| **Startup**</br>(0,8GHz core) | >500d         | >30d                     | **<1d**                                   |
+| **Biaya**                     | Mac Mini $599 | Kebanyakan Linux SBC </br>~$50 | **Semua Board Linux**</br>**Mulai dari $10** |
+
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+## 🦾 Demonstrasi
+
+### 🛠️ Alur Kerja Asisten Standar
+
+<table align="center">
+  <tr align="center">
+    <th><p align="center">🧩 Full-Stack Engineer</p></th>
+    <th><p align="center">🗂️ Pencatatan & Manajemen Perencanaan</p></th>
+    <th><p align="center">🔎 Pencarian Web & Pembelajaran</p></th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+  </tr>
+  <tr>
+    <td align="center">Develop • Deploy • Scale</td>
+    <td align="center">Jadwal • Otomasi • Memori</td>
+    <td align="center">Penemuan • Wawasan • Tren</td>
+  </tr>
+</table>
+
+### 📱 Jalankan di HP Android Lama
+
+Berikan kehidupan kedua untuk HP lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw. Panduan Cepat:
+
+1. **Instal [Termux](https://github.com/termux/termux-app)** (Unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play).
+2. **Jalankan perintah**
+
+```bash
+# Unduh rilis terbaru dari https://github.com/sipeed/picoclaw/releases
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard
+```
+
+Kemudian ikuti instruksi di bagian "Panduan Cepat" untuk menyelesaikan konfigurasi!
+
+<img src="assets/termux.jpg" alt="PicoClaw" width="512">
+
+### 🐜 Deploy Inovatif dengan Footprint Rendah
+
+PicoClaw dapat di-deploy di hampir semua perangkat Linux!
+
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk Home Assistant Minimal
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) untuk Pemeliharaan Server Otomatis
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) untuk Pemantauan Cerdas
+
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
+
+🌟 Lebih Banyak Kasus Deploy Menanti!
+
+## 📦 Instalasi
+
+### Instal dengan binary yang sudah dikompilasi
+
+Unduh binary untuk platform Anda dari halaman [Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Instal dari source (fitur terbaru, disarankan untuk pengembangan)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Build, tidak perlu instal
+make build
+
+# Build untuk berbagai platform
+make build-all
+
+# Build untuk Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Build dan Instal
+make install
+```
+
+**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya.
+
+## 📚 Dokumentasi
+
+Untuk panduan lengkap, lihat dokumen di bawah. README ini hanya berisi panduan cepat.
+
+| Topik | Deskripsi |
+|-------|-----------|
+| 🐳 [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent, konfigurasi Panduan Cepat |
+| 💬 [Aplikasi Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, dan lainnya |
+| ⚙️ [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sumber skill, sandbox keamanan, heartbeat |
+| 🔌 [Provider & Model](docs/providers.md) | 20+ provider LLM, routing model, konfigurasi model_list, arsitektur provider |
+| 🔄 [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
+| 🐛 [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya |
+| 🔧 [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan tool, kebijakan exec |
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Bergabung dengan Jaringan Sosial Agent
+
+Hubungkan Picoclaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi.
+
+**Baca `https://clawdchat.ai/skill.md` dan ikuti instruksi untuk bergabung dengan [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Referensi CLI
+
+| Perintah                  | Deskripsi                        |
+| ------------------------- | -------------------------------- |
+| `picoclaw onboard`        | Inisialisasi konfigurasi & workspace |
+| `picoclaw agent -m "..."` | Chat dengan agent                |
+| `picoclaw agent`          | Mode chat interaktif             |
+| `picoclaw gateway`        | Mulai gateway                    |
+| `picoclaw status`         | Tampilkan status                 |
+| `picoclaw version`        | Tampilkan info versi             |
+| `picoclaw cron list`      | Daftar semua tugas terjadwal     |
+| `picoclaw cron add ...`   | Tambah tugas terjadwal           |
+| `picoclaw cron disable`   | Nonaktifkan tugas terjadwal      |
+| `picoclaw cron remove`    | Hapus tugas terjadwal            |
+| `picoclaw skills list`    | Daftar skill yang terinstal      |
+| `picoclaw skills install` | Instal skill                     |
+| `picoclaw migrate`        | Migrasi data dari versi lama     |
+| `picoclaw auth login`     | Autentikasi dengan provider      |
+
+### Tugas Terjadwal / Pengingat
+
+PicoClaw mendukung pengingat terjadwal dan tugas berulang melalui tool `cron`:
+
+* **Pengingat satu kali**: "Ingatkan saya dalam 10 menit" → terpicu sekali setelah 10 menit
+* **Tugas berulang**: "Ingatkan saya setiap 2 jam" → terpicu setiap 2 jam
+* **Ekspresi cron**: "Ingatkan saya jam 9 pagi setiap hari" → menggunakan ekspresi cron
+
+## 🤝 Kontribusi & Roadmap
+
+PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca. 🤗
+
+Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) lengkap kami.
+
+Grup pengembang sedang dibangun, bergabunglah setelah PR pertama Anda di-merge!
+
+Grup Pengguna:
+
+discord: <https://discord.gg/V4sAZ9XWpN>
+
+<img src="assets/wechat.png" alt="PicoClaw" width="512">
--- a/README.it.md
+++ b/README.it.md
@ -0,0 +1,249 @@
+<div align="center">
+  <img src="assets/logo.webp" alt="PicoClaw" width="512">
+
+  <h1>PicoClaw: Assistente IA Ultra-Efficiente in Go</h1>
+
+  <h3>Hardware da $10 · <10MB RAM · Boot in <1s · 皮皮虾，我们走！</h3>
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [English](README.md)
+
+</div>
+
+---
+
+> **PicoClaw** è un progetto open-source indipendente avviato da [Sipeed](https://sipeed.com). È scritto interamente in **Go** — non è un fork di OpenClaw, NanoBot o di qualsiasi altro progetto.
+
+🦐 PicoClaw è un assistente IA personale ultra-leggero ispirato a [NanoBot](https://github.com/HKUDS/nanobot), riscritto da zero in Go attraverso un processo di auto-bootstrapping, in cui l'agente IA stesso ha guidato l'intera migrazione architetturale e l'ottimizzazione del codice.
+
+⚡️ Funziona su hardware da $10 con meno di 10MB di RAM: il 99% di memoria in meno rispetto a OpenClaw e il 98% più economico di un Mac mini!
+
+<table align="center">
+  <tr align="center">
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/picoclaw_mem.gif" width="360" height="240">
+      </p>
+    </td>
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/licheervnano.png" width="400" height="240">
+      </p>
+    </td>
+  </tr>
+</table>
+
+> [!CAUTION]
+> **🚨 SICUREZZA & CANALI UFFICIALI**
+>
+> * **NESSUNA CRYPTO:** PicoClaw non ha **NESSUN** token/coin ufficiale. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **TRUFFA**.
+>
+> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)**.
+> * **Attenzione:** Molti domini `.ai/.org/.com/.net/...` sono registrati da terze parti.
+> * **Attenzione:** PicoClaw è in fase di sviluppo iniziale e potrebbe avere problemi di sicurezza di rete non risolti. Non distribuire in ambienti di produzione prima della release v1.0.
+> * **Nota:** PicoClaw ha recentemente unito molte PR, il che potrebbe comportare un'impronta di memoria maggiore (10–20MB) nelle ultime versioni. Prevediamo di dare priorità all'ottimizzazione delle risorse non appena il set di funzionalità corrente raggiungerà uno stato stabile.
+
+## 📢 Novità
+
+2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), tracciamento dello stato dei sub-agent (`spawn_status`), hot-reload sperimentale del gateway, gate di sicurezza per cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K ⭐**!
+
+2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline di visione, store di memoria JSONL e routing dei modelli.
+
+2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e launcher Web UI.
+
+2026-02-26 🎉 PicoClaw ha raggiunto **20K stelle** in soli 17 giorni! Arrivate l'orchestrazione automatica dei canali e le interfacce di capacità.
+
+<details>
+<summary>Notizie precedenti...</summary>
+
+2026-02-16 🎉 PicoClaw ha raggiunto 12K stelle in una settimana! Ruoli di maintainer della community e [roadmap](ROADMAP.md) pubblicati ufficialmente.
+
+2026-02-13 🎉 PicoClaw ha raggiunto 5000 stelle in 4 giorni! Roadmap del progetto e gruppo sviluppatori in fase di avvio.
+
+2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli agenti IA su hardware da $10 con <10MB di RAM. 🦐 PicoClaw, andiamo!
+
+</details>
+
+## ✨ Caratteristiche
+
+🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo delle funzionalità principali di OpenClaw.*
+
+💰 **Costo Minimo**: Abbastanza efficiente da girare su hardware da $10 — il 98% più economico di un Mac mini.
+
+⚡️ **Avvio Fulmineo**: Tempo di avvio 400 volte più veloce, boot in meno di 1 secondo anche su un singolo core a 0,6 GHz.
+
+🌍 **Vera Portabilità**: Singolo binario autonomo per RISC-V, ARM, MIPS e x86. Un click e si parte!
+
+🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go in modo autonomo — 95% del core generato dall'Agent con perfezionamento umano nel ciclo.
+
+🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'agent.
+
+👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'agent — codifica base64 automatica per LLM multimodali.
+
+🧠 **Routing Intelligente**: Routing dei modelli basato su regole — le query semplici vanno verso modelli leggeri, risparmiando sui costi API.
+
+_*Le versioni recenti potrebbero usare 10–20MB a causa delle fusioni rapide di funzionalità. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._
+
+|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
+| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
+| **Linguaggio**                | TypeScript    | Python                   | **Go**                                    |
+| **RAM**                       | >1GB          | >100MB                   | **< 10MB***                               |
+| **Avvio**</br>(core 0,8 GHz)  | >500s         | >30s                     | **<1s**                                   |
+| **Costo**                     | Mac Mini $599 | La maggior parte degli SBC Linux </br>~$50 | **Qualsiasi scheda Linux**</br>**A partire da $10** |
+
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+## 🦾 Dimostrazione
+
+### 🛠️ Flussi di Lavoro Standard dell'Assistente
+
+<table align="center">
+  <tr align="center">
+    <th><p align="center">🧩 Ingegnere Full-Stack</p></th>
+    <th><p align="center">🗂️ Gestione Log & Pianificazione</p></th>
+    <th><p align="center">🔎 Ricerca Web & Apprendimento</p></th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+  </tr>
+  <tr>
+    <td align="center">Sviluppa • Distribuisci • Scala</td>
+    <td align="center">Pianifica • Automatizza • Memorizza</td>
+    <td align="center">Scopri • Analizza • Tendenze</td>
+  </tr>
+</table>
+
+### 📱 Usa su vecchi telefoni Android
+
+Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw. Avvio rapido:
+
+1. **Installa [Termux](https://github.com/termux/termux-app)** (Scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play).
+2. **Esegui i comandi**
+
+```bash
+# Scarica l'ultima release da https://github.com/sipeed/picoclaw/releases
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard
+```
+
+Poi segui le istruzioni nella sezione "Avvio Rapido" per completare la configurazione!
+
+<img src="assets/termux.jpg" alt="PicoClaw" width="512">
+
+### 🐜 Deploy Innovativo a Bassa Impronta
+
+PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux!
+
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un Assistente Domotico Minimale
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) per la Manutenzione Automatizzata dei Server
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) per il Monitoraggio Intelligente
+
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
+
+🌟 Molti altri scenari di deploy ti aspettano!
+
+## 📦 Installazione
+
+### Installa con binario precompilato
+
+Scarica il binario per la tua piattaforma dalla pagina delle [Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Installa dai sorgenti (ultime funzionalità, consigliato per lo sviluppo)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Compila, senza installare
+make build
+
+# Compila per più piattaforme
+make build-all
+
+# Compila per Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Compila e Installa
+make install
+```
+
+**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi.
+
+## 📚 Documentazione
+
+Per guide dettagliate, consulta la documentazione qui sotto. Il README copre solo l'avvio rapido.
+
+| Argomento | Descrizione |
+|-----------|-------------|
+| 🐳 [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent, configurazione rapida |
+| 💬 [App di Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom e altro |
+| ⚙️ [Configurazione](docs/it/configuration.md) | Variabili d'ambiente, struttura del workspace, sorgenti delle skill, sandbox di sicurezza, heartbeat |
+| 🔌 [Provider & Modelli](docs/providers.md) | 20+ provider LLM, routing dei modelli, configurazione model_list, architettura dei provider |
+| 🔄 [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
+| 🐛 [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni |
+| 🔧 [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec |
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Unisciti al Social Network degli Agent
+
+Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singolo messaggio tramite CLI o qualsiasi app di chat integrata.
+
+**Leggi `https://clawdchat.ai/skill.md` e segui le istruzioni per unirti a [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Riferimento CLI
+
+| Comando                   | Descrizione                        |
+| ------------------------- | ---------------------------------- |
+| `picoclaw onboard`        | Inizializza config & workspace     |
+| `picoclaw agent -m "..."` | Chatta con l'agent                 |
+| `picoclaw agent`          | Modalità chat interattiva          |
+| `picoclaw gateway`        | Avvia il gateway                   |
+| `picoclaw status`         | Mostra lo stato                    |
+| `picoclaw version`        | Mostra le info sulla versione      |
+| `picoclaw cron list`      | Elenca tutti i job pianificati     |
+| `picoclaw cron add ...`   | Aggiunge un job pianificato        |
+| `picoclaw cron disable`   | Disabilita un job pianificato      |
+| `picoclaw cron remove`    | Rimuove un job pianificato         |
+| `picoclaw skills list`    | Elenca le skill installate         |
+| `picoclaw skills install` | Installa una skill                 |
+| `picoclaw migrate`        | Migra i dati dalle versioni precedenti |
+| `picoclaw auth login`     | Autenticazione con i provider      |
+
+### Task Pianificati / Promemoria
+
+PicoClaw supporta promemoria pianificati e task ricorrenti tramite lo strumento `cron`:
+
+* **Promemoria una tantum**: "Ricordami tra 10 minuti" → si attiva una volta dopo 10 min
+* **Task ricorrenti**: "Ricordami ogni 2 ore" → si attiva ogni 2 ore
+* **Espressioni cron**: "Ricordami alle 9 ogni giorno" → usa un'espressione cron
+
+## 🤝 Contribuisci & Roadmap
+
+Le PR sono benvenute! Il codice è volutamente piccolo e leggibile. 🤗
+
+Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) completa.
+
+Gruppo sviluppatori in costruzione, unisciti dopo la tua prima PR accettata!
+
+Gruppi utenti:
+
+discord: <https://discord.gg/V4sAZ9XWpN>
+
+<img src="assets/wechat.png" alt="PicoClaw" width="512">
--- a/README.ja.md
+++ b/README.ja.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)

 </div>

--- a/README.md
+++ b/README.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **English**
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **English**

 </div>

@ -191,15 +191,510 @@ make install

 For detailed guides, see the docs below. The README covers quick start only.

-| Topic | Description |
-|-------|-------------|
-| 🐳 [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes, Quick Start configuration |
-| 💬 [Chat Apps](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, and more |
-| ⚙️ [Configuration](docs/configuration.md) | Environment variables, workspace layout, skill sources, security sandbox, heartbeat |
-| 🔌 [Providers & Models](docs/providers.md) | 20+ LLM providers, model routing, model_list configuration, provider architecture |
-| 🔄 [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
-| 🐛 [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
-| 🔧 [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies |
+```bash
+# 1. Clone this repo
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. First run — auto-generates docker/data/config.json then exits
+docker compose -f docker/docker-compose.yml --profile gateway up
+# The container prints "First-run setup complete." and stops.
+
+# 3. Set your API keys
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Start
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
+
+```bash
+# 5. Check logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Stop
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Launcher Mode (Web Console)
+
+The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Open http://localhost:18800 in your browser. The launcher manages the gateway process automatically.
+
+> [!WARNING]
+> The web console does not yet support authentication. Avoid exposing it to the public internet.
+
+### Agent Mode (One-shot)
+
+```bash
+# Ask a question
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Interactive mode
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Update
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Quick Start
+
+> [!TIP]
+> Set your API Key in `~/.picoclaw/config.json`. Get API Keys: [Volcengine (CodingPlan)](https://console.volcengine.com) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Web search is optional — get a free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month).
+
+**1. Initialize**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configure** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details.
+> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s).
+
+**3. Get API Keys**
+
+* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Web Search** (optional):
+  * [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month)
+  * [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface
+  * [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed)
+  * [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month)
+  * DuckDuckGo - Built-in fallback (no API key required)
+
+> **Note**: See `config.example.json` for a complete configuration template.
+
+**4. Chat**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+That's it! You have a working AI assistant in 2 minutes.
+
+---
+
+## 💬 Chat Apps
+
+Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom
+
+> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
+
+| Channel      | Setup                              |
+| ------------ | ---------------------------------- |
+| **Telegram** | Easy (just a token)                |
+| **Discord**  | Easy (bot token + intents)         |
+| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
+| **Matrix**   | Medium (homeserver + bot access token) |
+| **QQ**       | Easy (AppID + AppSecret)           |
+| **DingTalk** | Medium (app credentials)           |
+| **LINE**     | Medium (credentials + webhook URL) |
+| **WeCom AI Bot** | Medium (Token + AES key)       |
+
+<details>
+<summary><b>Telegram</b> (Recommended)</summary>
+
+**1. Create a bot**
+
+* Open Telegram, search `@BotFather`
+* Send `/newbot`, follow prompts
+* Copy the token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Get your user ID from `@userinfobot` on Telegram.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+**4. Telegram command menu (auto-registered at startup)**
+
+PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example `/start`, `/help`, `/show`, `/list`) so command menu and runtime behavior stay in sync.
+Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor.
+
+If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background.
+
+</details>
+
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Create a bot**
+
+* Go to <https://discord.com/developers/applications>
+* Create an application → Bot → Add Bot
+* Copy the bot token
+
+**2. Enable intents**
+
+* In the Bot settings, enable **MESSAGE CONTENT INTENT**
+* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
+
+**3. Get your User ID**
+* Discord Settings → Advanced → enable **Developer Mode**
+* Right-click your avatar → **Copy User ID**
+
+**4. Configure**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Invite the bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Open the generated invite URL and add the bot to your server
+
+**Optional: Group trigger mode**
+
+By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+You can also trigger by keyword prefixes (e.g. `!bot`):
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
+
+PicoClaw can connect to WhatsApp in two ways:
+
+- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false.
+
+**Configure (native)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+If `session_store_path` is empty, the session is stored in `&lt;workspace&gt;/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.
+
+</details>
+
+<details>
+<summary><b>QQ</b></summary>
+
+**1. Create a bot**
+
+- Go to [QQ Open Platform](https://q.qq.com/#)
+- Create an application → Get **AppID** and **AppSecret**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Create a bot**
+
+* Go to [Open Platform](https://open.dingtalk.com/)
+* Create an internal app
+* Copy Client ID and Client Secret
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+</details>
+
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Prepare bot account**
+
+* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted)
+* Create a bot user and obtain its access token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](docs/channels/matrix/README.md).
+
+</details>
+
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Create a LINE Official Account**
+
+- Go to [LINE Developers Console](https://developers.line.biz/)
+- Create a provider → Create a Messaging API channel
+- Copy **Channel Secret** and **Channel Access Token**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
+
+**3. Set up Webhook URL**
+
+LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:
+
+```bash
+# Example with ngrok (gateway default port is 18790)
+ngrok http 18790
+```
+
+Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**.
+
+**4. Run**
+
+```bash
+picoclaw gateway
+```
+
+> In group chats, the bot responds only when @mentioned. Replies quote the original message.
+
+</details>
+
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw supports three types of WeCom integration:
+
+**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats
+**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only
+**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat
+
+See [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions.
+
+**Quick Setup - WeCom AI Bot:**
+
+**1. Create an AI Bot**
+
+* Go to WeCom Admin Console → AI Bot
+* Create a new AI Bot → Set name, avatar, etc.
+* Copy **Bot ID** and **Secret**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "allow_from": [],
+      "welcome_message": "Hello! How can I help you?"
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery.
+
+</details>

 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network

--- a/README.pt-br.md
+++ b/README.pt-br.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)

 </div>

--- a/README.vi.md
+++ b/README.vi.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)

 </div>

--- a/README.zh.md
+++ b/README.zh.md
@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)

 </div>

--- a/config/config.example.json
+++ b/config/config.example.json
@ -8,7 +8,11 @@
      "temperature": 0.7,
      "max_tool_iterations": 20,
      "summarize_message_threshold": 20,
-      "summarize_token_percent": 75
+      "summarize_token_percent": 75,
+      "tool_feedback": {
+        "enabled": false,
+        "max_args_length": 300
+      }
    }
  },
  "model_list": [
@ -194,6 +198,8 @@
    "wecom_aibot": {
      "_comment": "WeCom AI Bot (智能机器人) - Official WeCom AI Bot integration, supports proactive messaging and private chats.",
      "enabled": false,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
--- a/docs/channels/qq/README.zh.md
+++ b/docs/channels/qq/README.zh.md
@ -11,18 +11,20 @@ PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "max_base64_file_size_mib": 0
    }
  }
 }
 ```

-| 字段       | 类型   | 必填 | 描述                             |
-| ---------- | ------ | ---- | -------------------------------- |
-| enabled    | bool   | 是   | 是否启用 QQ Channel              |
-| app_id     | string | 是   | QQ 机器人应用的 App ID           |
-| app_secret | string | 是   | QQ 机器人应用的 App Secret       |
-| allow_from | array  | 否   | 用户ID白名单，空表示允许所有用户 |
+| 字段                 | 类型   | 必填 | 描述                                                         |
+| -------------------- | ------ | ---- | ------------------------------------------------------------ |
+| enabled              | bool   | 是   | 是否启用 QQ Channel                                          |
+| app_id               | string | 是   | QQ 机器人应用的 App ID                                       |
+| app_secret           | string | 是   | QQ 机器人应用的 App Secret                                   |
+| allow_from           | array  | 否   | 用户ID白名单，空表示允许所有用户                             |
+| max_base64_file_size_mib | int | 否   | 本地文件转 base64 上传的最大体积，单位 MiB；`0` 表示不限制。仅影响本地文件，不影响 URL 直传 |

 ## 设置流程

--- a/docs/channels/wecom/wecom_aibot/README.zh.md
+++ b/docs/channels/wecom/wecom_aibot/README.zh.md
@ -1,6 +1,9 @@
 # 企业微信智能机器人 (AI Bot)

-企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议，并支持超时后通过 `response_url` 主动推送最终回复。
+企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。PicoClaw 当前同时支持两种接入模式：
+
+- WebSocket 长连接模式：使用 `bot_id` + `secret`，优先级更高，推荐使用
+- Webhook 短连接模式：使用 `token` + `encoding_aes_key`，兼容传统回调，并支持超时后通过 `response_url` 主动推送最终回复

 ## 与其他 WeCom 通道的对比

@ -14,6 +17,25 @@

 ## 配置

+### WebSocket 长连接模式（推荐）
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+### Webhook 短连接模式
+
 ```json
 {
  "channels": {
@ -24,38 +46,68 @@
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly.",
      "max_steps": 10
    }
  }
 }
 ```

-| 字段             | 类型   | 必填 | 描述                                               |
-| ---------------- | ------ | ---- | -------------------------------------------------- |
-| token            | string | 是   | 回调验证令牌，在 AI Bot 管理页面配置               |
-| encoding_aes_key | string | 是   | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成       |
-| webhook_path     | string | 否   | Webhook 路径（默认：/webhook/wecom-aibot）         |
-| allow_from       | array  | 否   | 用户 ID 白名单，空数组表示允许所有用户             |
-| welcome_message  | string | 否   | 用户进入聊天时发送的欢迎语，留空则不发送           |
-| reply_timeout    | int    | 否   | 回复超时时间（秒，默认：5）                        |
-| max_steps        | int    | 否   | Agent 最大执行步骤数（默认：10）                   |
+### WebSocket 模式字段
+
+| 字段   | 类型   | 必填 | 描述                                       |
+|--------|--------|------|--------------------------------------------|
+| bot_id | string | 是   | AI Bot 的唯一标识，在 AI Bot 管理页面配置 |
+| secret | string | 是   | AI Bot 的密钥，在 AI Bot 管理页面配置     |
+
+### Webhook 模式字段
+
+| 字段             | 类型   | 必填 | 描述                                         |
+|------------------|--------|------|----------------------------------------------|
+| token            | string | 是   | 回调验证令牌，在 AI Bot 管理页面配置         |
+| encoding_aes_key | string | 是   | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成 |
+| webhook_path     | string | 否   | Webhook 路径，默认 `/webhook/wecom-aibot`    |
+| processing_message | string | 否 | 流式超时后返回给用户的提示语                 |
+
+### 通用字段
+
+| 字段            | 类型   | 必填 | 描述                                     |
+|-----------------|--------|------|------------------------------------------|
+| allow_from      | array  | 否   | 用户 ID 白名单，空数组表示允许所有用户   |
+| welcome_message | string | 否   | 用户进入聊天时发送的欢迎语，留空则不发送 |
+| reply_timeout   | int    | 否   | 回复超时时间（秒，默认：5）              |
+| max_steps       | int    | 否   | Agent 最大执行步骤数（默认：10）         |
+
+## 模式选择
+
+- 当 `bot_id` 和 `secret` 同时存在时，PicoClaw 会优先使用 WebSocket 长连接模式
+- 否则，当 `token` 和 `encoding_aes_key` 同时存在时，PicoClaw 会使用 Webhook 短连接模式

 ## 设置流程

+### WebSocket 长连接模式
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
+3. 在 AI Bot 配置页面，配置 Bot 的名称、头像等信息，获取 `Bot ID` 和 `Secret`
+4. 在 PicoClaw 配置文件中添加上述配置，重启 PicoClaw
+
+### Webhook 短连接模式
+
 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
 2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
 3. 在 AI Bot 配置页面，填写"消息接收"信息：
   - **URL**：`http://<your-server-ip>:18791/webhook/wecom-aibot`
   - **Token**：随机生成或自定义
   - **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
-4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存（企业微信会发送验证请求）
+4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存

 > [!TIP]
-> 服务器需要能被企业微信服务器访问。如在内网/本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。
+> 服务器需要能被企业微信服务器访问。如在内网或本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。

-## 流式响应协议
+## Webhook 模式的流式响应协议

-WeCom AI Bot 使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：
+Webhook 模式使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：

 ```
 用户发消息
@ -71,16 +123,24 @@ PicoClaw 立即返回 {finish: false}（Agent 开始处理）
  └─ Agent 完成 → 返回 {finish: true, content: "回答内容"}
 ```

-**超时处理**（任务超过 30 秒）：
+**超时处理**（任务超过约 30 秒）：

-若 Agent 处理时间超过约 30 秒（企业微信最大轮询窗口为 6 分钟），PicoClaw 会：
+若 Agent 处理时间超过轮询窗口，PicoClaw 会：

-1. 立即关闭流，向用户显示「⏳ 正在处理中，请稍候，结果将稍后发送。」
+1. 立即关闭流，向用户显示 `processing_message` 提示语
 2. Agent 继续在后台运行
 3. Agent 完成后，通过消息中携带的 `response_url` 将最终回复主动推送给用户

 > `response_url` 由企业微信颁发，有效期 1 小时，只可使用一次，无需加密，直接 POST markdown 消息体即可。

+## 超时提示语
+
+配置 `processing_message` 后，当 Webhook 模式的流式轮询超时并切换到 `response_url` 主动推送模式时，PicoClaw 会先返回这段提示语来结束当前流。
+
+```json
+"processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+```
+
 ## 欢迎语

 配置 `welcome_message` 后，当用户打开与 AI Bot 的聊天窗口时（`enter_chat` 事件），PicoClaw 会自动回复该欢迎语。留空则静默忽略。
@ -91,11 +151,17 @@ PicoClaw 立即返回 {finish: false}（Agent 开始处理）

 ## 常见问题

+### WebSocket 模式无法连接
+
+- 检查 `bot_id` 和 `secret` 是否填写正确
+- 查看日志中是否有 WebSocket 连接或鉴权失败信息
+- 确认服务器可以访问企业微信长连接接口
+
 ### 回调 URL 验证失败

- 确认服务器防火墙已开放对应端口（默认 18791）
 - 确认 `token` 与 `encoding_aes_key` 填写正确
- 检查 PicoClaw 日志是否收到了来自企业微信的 GET 请求
+- 确认服务器防火墙已开放对应端口
+- 检查 PicoClaw 日志是否收到了来自企业微信的验证请求

 ### 消息没有回复

@ -105,12 +171,12 @@ PicoClaw 立即返回 {finish: false}（Agent 开始处理）

 ### 超长任务没有收到最终推送

- 确认消息回调中携带了 `response_url`（仅企业微信新版 AI Bot 支持）
- 确认服务器能主动访问外网（需向 `response_url` POST 请求）
+- 确认消息回调中携带了 `response_url`
+- 确认服务器能主动访问外网
 - 查看日志关键词 `response_url mode` 和 `Sending reply via response_url`

 ## 参考文档

- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/100719)
+- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/101463)
 - [流式响应协议说明](https://developer.work.weixin.qq.com/document/path/100719)
 - [response_url 主动回复](https://developer.work.weixin.qq.com/document/path/101138)
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@ -414,7 +414,8 @@ picoclaw gateway
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
-      "welcome_message": "Hello! How can I help you?"
+      "welcome_message": "Hello! How can I help you?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
 }
--- a/docs/configuration.md
+++ b/docs/configuration.md
@ -42,13 +42,15 @@ PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspa
 ├── state/            # Persistent state (last channel, etc.)
 ├── cron/             # Scheduled jobs database
 ├── skills/           # Custom skills
-├── AGENTS.md         # Agent behavior guide
+├── AGENT.md          # Agent behavior guide
 ├── HEARTBEAT.md      # Periodic task prompts (checked every 30 min)
 ├── IDENTITY.md       # Agent identity
 ├── SOUL.md           # Agent soul
 └── USER.md           # User preferences
 ```

+> **Note:** Changes to `AGENT.md`, `SOUL.md`, `USER.md` and `memory/MEMORY.md` are automatically detected at runtime via file modification time (mtime) tracking. You do **not** need to restart the gateway after editing these files — the agent picks up the new content on the next request.
+
 ### Skill Sources

 By default, skills are loaded from:
@ -69,6 +71,135 @@ export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
 - Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup.
 - Unknown slash command (for example `/foo`) passes through to normal LLM processing.
 - Registered but unsupported command on the current channel (for example `/show` on WhatsApp) returns an explicit user-facing error and stops further processing.
+
+### Agent Bindings (Route messages to specific agents)
+
+Use `bindings` in `config.json` to route incoming messages to different agents by channel/account/context.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-4o-mini"
+    },
+    "list": [
+      { "id": "main", "default": true, "name": "Main Assistant" },
+      { "id": "support", "name": "Support Assistant" },
+      { "id": "sales", "name": "Sales Assistant" }
+    ]
+  },
+  "bindings": [
+    {
+      "agent_id": "support",
+      "match": {
+        "channel": "telegram",
+        "account_id": "*",
+        "peer": { "kind": "direct", "id": "user123" }
+      }
+    },
+    {
+      "agent_id": "sales",
+      "match": {
+        "channel": "discord",
+        "account_id": "my-discord-bot",
+        "guild_id": "987654321"
+      }
+    }
+  ]
+}
+```
+
+#### `bindings` fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent_id` | Yes | Target agent id in `agents.list` |
+| `match.channel` | Yes | Channel name (e.g. `telegram`, `discord`) |
+| `match.account_id` | No | Channel account filter. Use `"*"` for all accounts of that channel. If omitted, only default account is matched |
+| `match.peer.kind` + `match.peer.id` | No | Exact peer match (e.g. direct chat / topic / group id) |
+| `match.guild_id` | No | Guild/server-level match |
+| `match.team_id` | No | Team/workspace-level match |
+
+#### Matching priority
+
+When multiple bindings exist, PicoClaw resolves in this order:
+
+1. `peer`
+2. `parent_peer` (for thread/topic parent contexts)
+3. `guild_id`
+4. `team_id`
+5. `account_id` (non-wildcard)
+6. channel wildcard (`account_id: "*"`)
+7. default agent
+
+If a binding points to a missing `agent_id`, PicoClaw falls back to the default agent.
+
+#### How matching works (step-by-step)
+
+1. PicoClaw first filters bindings by `match.channel` (must equal current channel).
+2. It then filters by `match.account_id`:
+   - omitted: match only the channel's default account
+   - `"*"`: match all accounts on this channel
+   - explicit value: exact account id match (case-insensitive)
+3. From the remaining candidates, it applies the priority chain above and stops at the first hit.
+
+In other words: **channel + account form the candidate set; peer/guild/team then decide final winner**.
+
+#### Common recipes
+
+**1) Route one specific DM user to a specialist agent**
+
+```json
+{
+  "agent_id": "support",
+  "match": {
+    "channel": "telegram",
+    "account_id": "*",
+    "peer": { "kind": "direct", "id": "user123" }
+  }
+}
+```
+
+**2) Route one Discord server (guild) to a dedicated agent**
+
+```json
+{
+  "agent_id": "sales",
+  "match": {
+    "channel": "discord",
+    "account_id": "my-discord-bot",
+    "guild_id": "987654321"
+  }
+}
+```
+
+**3) Route all remaining traffic of a channel to a fallback agent**
+
+```json
+{
+  "agent_id": "main",
+  "match": {
+    "channel": "discord",
+    "account_id": "*"
+  }
+}
+```
+
+#### Authoring guidelines (important)
+
+- Keep exactly one clear default agent in `agents.list` (`"default": true`).
+- Put specific rules (`peer`, `guild_id`, `team_id`) and broad rules (`account_id: "*"` only) together safely; priority already guarantees specific rules win.
+- Avoid duplicate rules with the same specificity and match values. If duplicates exist, the first matching entry in the config array wins.
+- Ensure every `agent_id` exists in `agents.list`; unknown IDs silently fall back to default.
+
+#### Troubleshooting checklist
+
+- **Rule not taking effect?** Check `match.channel` spelling first (must be exact).
+- **Expected account-specific routing but still using default?** Verify `match.account_id` equals actual runtime account id.
+- **Wildcard catches too much traffic?** Add more specific `peer/guild/team` rules for critical paths.
+- **Unexpected default fallback?** Confirm `agent_id` exists and is not misspelled.
+
 ### 🔒 Security Sandbox

 PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
--- a/docs/debug.md
+++ b/docs/debug.md
@ -31,3 +31,69 @@ When this flag is active, the global truncation function is disabled. This is ex
 * Verifying the exact syntax of the messages sent to the provider.
 * Reading the complete output of tools like `exec`, `web_fetch`, or `read_file`.
 * Debugging the session history saved in memory.
+
+## Tool Call Visibility in Debug Logs
+
+When debug mode is active, the agent emits structured log entries at each stage of the tool execution lifecycle. These entries carry a `component=agent` label and use `INFO` or `DEBUG` level depending on the amount of detail:
+
+| Log message | Level | Key fields | Description |
+|---|---|---|---|
+| `LLM requested tool calls` | INFO | `tools`, `count`, `iteration` | List of tool names the model decided to call |
+| `Tool call: <name>(<args>)` | INFO | `tool`, `iteration` | The tool name and a preview of its arguments (truncated to 200 chars) |
+| `Sent tool result to user` | DEBUG | `tool`, `content_len` | Fired when a tool result is forwarded to the chat channel |
+| `TTL tick after tool execution` | DEBUG | `agent_id`, `iteration` | MCP tool-discovery TTL decrement after each tool round |
+| `Async tool completed, publishing result` | INFO | `tool`, `content_len`, `channel` | Only for tools that run asynchronously in the background |
+
+### Reading a tool call log entry
+
+A typical synchronous tool call produces two consecutive lines in the console:
+
+```
+[...] [INFO] agent: LLM requested tool calls {tools=[web_search], count=1, iteration=1}
+[...] [INFO] agent: Tool call: web_search({"query":"picoclaw release notes"}) {tool=web_search, iteration=1}
+```
+
+The arguments preview is hard-capped at **200 characters** in the logs regardless of the `--no-truncate` flag, because it belongs to the `INFO`-level path. Use `--no-truncate` together with `--debug` to see the full `tools_json` field emitted by the `Full LLM request` DEBUG entry, which contains every tool definition sent to the model.
+
+## Real-Time Tool Feedback in Chat (tool_feedback)
+
+Debug logs are server-side only. If you want the agent to send a visible notification directly into the chat channel every time it executes a tool—useful when sharing the bot with other users or for transparency—enable the `tool_feedback` feature in `config.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "tool_feedback": {
+        "enabled": true,
+        "max_args_length": 300
+      }
+    }
+  }
+}
+```
+
+When `enabled` is `true`, every tool call sends a short message to the chat before the tool result is returned to the model. The message looks like:
+
+```bash
+🔧 `web_search`
+{"query": "picoclaw release notes"}
+```
+
+
+### Options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | bool | `false` | Send a chat notification for each tool call |
+| `max_args_length` | int | `300` | Maximum characters of the serialised arguments included in the notification |
+
+### Environment variables
+
+Both fields can also be set via environment variables:
+
+```bash
+PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED=true
+PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH=300
+```
+
+> **Note:** `tool_feedback` is independent of `--debug` mode. It works in production and does not require the gateway to be started with any special flag.
--- a/docs/fr/chat-apps.md
+++ b/docs/fr/chat-apps.md
@ -410,7 +410,8 @@ picoclaw gateway
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
-      "welcome_message": "Hello! How can I help you?"
+      "welcome_message": "Hello! How can I help you?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
 }
--- a/docs/fr/configuration.md
+++ b/docs/fr/configuration.md
@ -42,13 +42,14 @@ PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.
 ├── state/            # État persistant (dernier canal, etc.)
 ├── cron/             # Base de données des tâches planifiées
 ├── skills/           # Compétences personnalisées
-├── AGENTS.md         # Guide de comportement de l'agent
+├── AGENT.md          # Guide de comportement de l'agent
 ├── HEARTBEAT.md      # Invites de tâches périodiques (vérifiées toutes les 30 min)
-├── IDENTITY.md       # Identité de l'agent
 ├── SOUL.md           # Âme de l'agent
 └── USER.md           # Préférences utilisateur
 ```

+> **Remarque :** Les modifications apportées à `AGENT.md`, `SOUL.md`, `USER.md` et `memory/MEMORY.md` sont détectées automatiquement au moment de l'exécution via le suivi de la date de modification (mtime). Il n'est **pas nécessaire de redémarrer le gateway** après avoir modifié ces fichiers — l'agent charge le nouveau contenu à la prochaine requête.
+
 ### Sources de Compétences

 Par défaut, les compétences sont chargées depuis :
--- a/docs/fr/tools_configuration.md
+++ b/docs/fr/tools_configuration.md
@ -70,9 +70,32 @@ L'outil exec est utilisé pour exécuter des commandes shell.

 | Config                 | Type  | Par défaut | Description                                    |
 |------------------------|-------|------------|------------------------------------------------|
+| `enabled`              | bool  | true       | Activer l'outil exec                           |
 | `enable_deny_patterns` | bool  | true       | Activer le blocage par défaut des commandes dangereuses |
 | `custom_deny_patterns` | array | []         | Modèles de refus personnalisés (expressions régulières) |

+### Désactivation de l'Outil Exec
+
+Pour désactiver complètement l'outil `exec`, définissez `enabled` à `false` :
+
+**Via le fichier de configuration :**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via la variable d'environnement :**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note :** Lorsqu'il est désactivé, l'agent ne pourra pas exécuter de commandes shell. Cela affecte également la capacité de l'outil Cron à exécuter des commandes shell planifiées.
+
 ### Fonctionnalité

 - **`enable_deny_patterns`** : Définir à `false` pour désactiver complètement les modèles de blocage par défaut des commandes dangereuses
@ -175,7 +198,6 @@ Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger
 | `env_file` | string | non      | Chemin vers le fichier d'environnement pour le processus stdio |
 | `url`      | string | sse/http | URL du point de terminaison pour le transport `sse`/`http` |
 | `headers`  | object | non      | En-têtes HTTP pour le transport `sse`/`http` |
-| `timeout`  | int    | non      | Délai d'attente des appels d'outils en secondes (défaut : 60) |

 ### Comportement du transport

@ -224,8 +246,7 @@ Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -331,6 +352,7 @@ Toutes les options de configuration peuvent être remplacées via des variables
 Par exemple :

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/docs/it/configuration.md
+++ b/docs/it/configuration.md
@ -0,0 +1,219 @@
+# ⚙️ Guida alla Configurazione
+
+> Torna al [README](../../README.md)
+
+## ⚙️ Configurazione
+
+File di configurazione: `~/.picoclaw/config.json`
+
+### Variabili d'Ambiente
+
+Puoi sovrascrivere i percorsi predefiniti usando variabili d'ambiente. Questo è utile per installazioni portatili, distribuzioni containerizzate, o per eseguire picoclaw come servizio di sistema. Queste variabili sono indipendenti e controllano percorsi diversi.
+
+| Variabile         | Descrizione                                                                                                                             | Percorso Predefinito      |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Sovrascrive il percorso al file di configurazione. Indica direttamente a picoclaw quale `config.json` caricare, ignorando tutte le altre posizioni. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Sovrascrive la directory radice per i dati di picoclaw. Modifica la posizione predefinita del `workspace` e delle altre directory dati.  | `~/.picoclaw`             |
+
+**Esempi:**
+
+```bash
+# Esegui picoclaw usando un file di configurazione specifico
+# Il percorso del workspace verrà letto da quel file di configurazione
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Esegui picoclaw con tutti i dati salvati in /opt/picoclaw
+# La configurazione verrà caricata dal percorso predefinito ~/.picoclaw/config.json
+# Il workspace verrà creato in /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Usa entrambi per un setup completamente personalizzato
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Struttura del Workspace
+
+PicoClaw salva i dati nel workspace configurato (predefinito: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Sessioni di conversazione e cronologia
+├── memory/           # Memoria a lungo termine (MEMORY.md)
+├── state/            # Stato persistente (ultimo canale, ecc.)
+├── cron/             # Database dei job pianificati
+├── skills/           # Skill personalizzate
+├── AGENTS.md         # Guida al comportamento dell'agent
+├── HEARTBEAT.md      # Prompt per task periodici (controllato ogni 30 min)
+├── IDENTITY.md       # Identità dell'agent
+├── SOUL.md           # Anima dell'agent
+└── USER.md           # Preferenze dell'utente
+```
+
+> **Nota:** Le modifiche a `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md` e `memory/MEMORY.md` vengono rilevate automaticamente a runtime tramite il tracciamento della data di modifica (mtime). **Non è necessario riavviare il gateway** dopo aver modificato questi file — l'agent caricherà il nuovo contenuto alla prossima richiesta.
+
+### Sorgenti delle Skill
+
+Per impostazione predefinita, le skill vengono caricate da:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (globale)
+3. `<current-working-directory>/skills` (builtin)
+
+Per configurazioni avanzate/di test, puoi sovrascrivere la directory radice delle skill builtin con:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Politica Unificata di Esecuzione dei Comandi
+
+- I comandi slash generici vengono eseguiti tramite un unico percorso in `pkg/agent/loop.go` via `commands.Executor`.
+- Gli adattatori dei canali non consumano più localmente i comandi generici; inoltrano il testo in entrata al percorso bus/agent. Telegram registra ancora automaticamente i comandi supportati all'avvio.
+- Un comando slash sconosciuto (ad esempio `/foo`) viene passato all'elaborazione LLM come se fosse un messaggio dell'utente.
+- Un comando registrato ma non supportato sul canale corrente (ad esempio `/show` su WhatsApp) restituisce un errore esplicito all'utente e interrompe l'elaborazione.
+
+### 🔒 Sandbox di Sicurezza
+
+PicoClaw esegue in un ambiente sandboxed per impostazione predefinita. L'agent può accedere solo ai file ed eseguire comandi all'interno del workspace configurato.
+
+#### Configurazione Predefinita
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Opzione                 | Predefinito             | Descrizione                                          |
+| ----------------------- | ----------------------- | ---------------------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Directory di lavoro dell'agent                       |
+| `restrict_to_workspace` | `true`                  | Limita l'accesso a file/comandi al workspace         |
+
+#### Strumenti Protetti
+
+Quando `restrict_to_workspace: true`, i seguenti strumenti sono in sandbox:
+
+| Strumento     | Funzione                  | Restrizione                                          |
+| ------------- | ------------------------- | ---------------------------------------------------- |
+| `read_file`   | Legge file                | Solo file all'interno del workspace                  |
+| `write_file`  | Scrive file               | Solo file all'interno del workspace                  |
+| `list_dir`    | Elenca directory          | Solo directory all'interno del workspace             |
+| `edit_file`   | Modifica file             | Solo file all'interno del workspace                  |
+| `append_file` | Aggiunge ai file          | Solo file all'interno del workspace                  |
+| `exec`        | Esegue comandi            | I percorsi dei comandi devono essere nel workspace   |
+
+#### Protezione Exec Aggiuntiva
+
+Anche con `restrict_to_workspace: false`, lo strumento `exec` blocca questi comandi pericolosi:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Cancellazione di massa
+* `format`, `mkfs`, `diskpart` — Formattazione del disco
+* `dd if=` — Imaging del disco
+* Scrittura su `/dev/sd[a-z]` — Scritture dirette su disco
+* `shutdown`, `reboot`, `poweroff` — Spegnimento del sistema
+* Fork bomb `:(){ :|:& };:`
+
+### Controllo Accesso ai File
+
+| Chiave di configurazione | Tipo | Predefinito | Descrizione |
+|--------------------------|------|-------------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Percorsi aggiuntivi consentiti per la lettura al di fuori del workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Percorsi aggiuntivi consentiti per la scrittura al di fuori del workspace |
+
+### Sicurezza Exec
+
+| Chiave di configurazione | Tipo | Predefinito | Descrizione |
+|--------------------------|------|-------------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Consente lo strumento exec da canali remoti (Telegram/Discord ecc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Abilita l'intercettazione dei comandi pericolosi |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Pattern regex personalizzati da bloccare |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Pattern regex personalizzati da consentire |
+
+> **Nota di sicurezza:** La protezione dei symlink è abilitata per impostazione predefinita — tutti i percorsi file vengono risolti tramite `filepath.EvalSymlinks` prima del confronto con la whitelist, prevenendo attacchi di escape tramite symlink.
+
+#### Limitazione Nota: Processi Figlio degli Strumenti di Build
+
+Il controllo di sicurezza exec ispeziona solo la riga di comando avviata direttamente da PicoClaw. Non ispeziona ricorsivamente i processi figlio generati da strumenti di sviluppo consentiti come `make`, `go run`, `cargo`, `npm run` o script di build personalizzati.
+
+Ciò significa che un comando di primo livello può comunque compilare o avviare altri binari dopo aver superato il controllo iniziale. In pratica, tratta gli script di build, i Makefile, gli script di pacchetti e i binari generati come codice eseguibile che richiede lo stesso livello di revisione di un comando shell diretto.
+
+Per ambienti ad alto rischio:
+
+* Esamina gli script di build prima dell'esecuzione.
+* Preferisci l'approvazione/revisione manuale per i workflow di compilazione ed esecuzione.
+* Esegui PicoClaw in un container o VM se hai bisogno di un isolamento più forte di quello fornito dal controllo integrato.
+
+#### Esempi di Errore
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Disabilitare le Restrizioni (Rischio di Sicurezza)
+
+Se hai bisogno che l'agent acceda a percorsi al di fuori del workspace:
+
+**Metodo 1: File di configurazione**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Metodo 2: Variabile d'ambiente**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Attenzione**: Disabilitare questa restrizione consente all'agent di accedere a qualsiasi percorso sul tuo sistema. Usare con cautela solo in ambienti controllati.
+
+#### Coerenza dei Confini di Sicurezza
+
+L'impostazione `restrict_to_workspace` si applica in modo coerente a tutti i percorsi di esecuzione:
+
+| Percorso di esecuzione | Confine di sicurezza              |
+| ---------------------- | --------------------------------- |
+| Main Agent             | `restrict_to_workspace` ✅        |
+| Subagent / Spawn       | Eredita la stessa restrizione ✅  |
+| Heartbeat tasks        | Eredita la stessa restrizione ✅  |
+
+Tutti i percorsi condividono la stessa restrizione del workspace — non è possibile aggirare il confine di sicurezza tramite subagent o task pianificati.
+
+### Heartbeat (Task Periodici)
+
+PicoClaw può eseguire task periodici automaticamente. Crea un file `HEARTBEAT.md` nel tuo workspace:
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+L'agent leggerà questo file ogni 30 minuti (configurabile) ed eseguirà tutti i task usando gli strumenti disponibili.
+
+#### Task Asincroni con Spawn
+
+Per task di lunga durata (ricerca web, chiamate API), usa lo strumento `spawn` per creare un **subagent**:
+
+```markdown
+# Periodic Tasks
+```
--- a/docs/ja/chat-apps.md
+++ b/docs/ja/chat-apps.md
@ -510,7 +510,8 @@ picoclaw gateway
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
-      "welcome_message": "こんにちは！何かお手伝いできますか？"
+      "welcome_message": "こんにちは！何かお手伝いできますか？",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
 }
--- a/docs/ja/configuration.md
+++ b/docs/ja/configuration.md
@ -42,13 +42,15 @@ PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw
 ├── state/            # 永続化状態 (最後のチャネルなど)
 ├── cron/             # スケジュールジョブデータベース
 ├── skills/           # カスタムスキル
-├── AGENTS.md         # Agent 動作ガイド
+├── AGENT.md          # Agent 動作ガイド
 ├── HEARTBEAT.md      # 定期タスクプロンプト (30 分ごとにチェック)
 ├── IDENTITY.md       # Agent アイデンティティ
 ├── SOUL.md           # Agent ソウル/性格
 └── USER.md           # ユーザー設定
 ```

+> **注意：** `AGENT.md`、`SOUL.md`、`USER.md` および `memory/MEMORY.md` への変更は、ファイル更新時刻（mtime）の追跡により実行時に自動検出されます。これらのファイルを編集した後に **gateway を再起動する必要はありません** — Agent は次のリクエスト時に最新の内容を自動的に読み込みます。
+
 ### スキルソース

 デフォルトでは、スキルは以下の順序で読み込まれます：
--- a/docs/ja/tools_configuration.md
+++ b/docs/ja/tools_configuration.md
@ -70,9 +70,32 @@ Exec ツールはシェルコマンドの実行に使用されます。

 | 設定項目               | 型    | デフォルト | 説明                               |
 |------------------------|-------|------------|------------------------------------|
+| `enabled`              | bool  | true       | Exec ツールを有効にする            |
 | `enable_deny_patterns` | bool  | true       | デフォルトの危険コマンドブロックを有効にする |
 | `custom_deny_patterns` | array | []         | カスタム拒否パターン（正規表現）   |

+### Exec ツールの無効化
+
+`exec` ツールを完全に無効にするには、`enabled` を `false` に設定します：
+
+**設定ファイル経由：**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**環境変数経由：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 無効にすると、エージェントはシェルコマンドを実行できなくなります。これは Cron ツールがスケジュールされたシェルコマンドを実行する能力にも影響します。
+
 ### 機能

 - **`enable_deny_patterns`**：`false` に設定すると、デフォルトの危険コマンドブロックパターンを完全に無効にします
@ -175,7 +198,6 @@ MCP ツールは外部の Model Context Protocol サーバーとの統合を可
 | `env_file` | string | いいえ   | stdio プロセスの環境ファイルパス       |
 | `url`      | string | sse/http | `sse`/`http` トランスポートのエンドポイント URL |
 | `headers`  | object | いいえ   | `sse`/`http` トランスポートの HTTP ヘッダー |
-| `timeout`  | int    | いいえ   | ツール呼び出しのタイムアウト秒数（デフォルト: 60） |

 ### トランスポートの動作

@ -224,8 +246,7 @@ MCP ツールは外部の Model Context Protocol サーバーとの統合を可
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -331,6 +352,7 @@ Skills ツールは ClawHub などのレジストリを通じたスキルの発
 例：

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/docs/pt-br/configuration.md
+++ b/docs/pt-br/configuration.md
@ -42,13 +42,15 @@ O PicoClaw armazena dados no seu workspace configurado (padrão: `~/.picoclaw/wo
 ├── state/            # Estado persistente (último canal, etc.)
 ├── cron/             # Banco de dados de tarefas agendadas
 ├── skills/           # Skills personalizadas
-├── AGENTS.md         # Guia de comportamento do agente
+├── AGENT.md          # Guia de comportamento do agente
 ├── HEARTBEAT.md      # Prompts de tarefas periódicas (verificados a cada 30 min)
 ├── IDENTITY.md       # Identidade do agente
 ├── SOUL.md           # Alma do agente
 └── USER.md           # Preferências do usuário
 ```

+> **Nota:** Alterações em `AGENT.md`, `SOUL.md`, `USER.md` e `memory/MEMORY.md` são detectadas automaticamente em tempo de execução via rastreamento de data de modificação (mtime). **Não é necessário reiniciar o gateway** após editar esses arquivos — o agente carrega o novo conteúdo na próxima requisição.
+
 ### Fontes de Skills

 Por padrão, as skills são carregadas de:
--- a/docs/pt-br/tools_configuration.md
+++ b/docs/pt-br/tools_configuration.md
@ -70,9 +70,32 @@ A ferramenta exec é usada para executar comandos shell.

 | Config                 | Tipo  | Padrão | Descrição                                      |
 |------------------------|-------|--------|-------------------------------------------------|
+| `enabled`              | bool  | true   | Habilitar a ferramenta exec                     |
 | `enable_deny_patterns` | bool  | true   | Habilitar bloqueio padrão de comandos perigosos |
 | `custom_deny_patterns` | array | []     | Padrões de negação personalizados (expressões regulares) |

+### Desabilitando a Ferramenta Exec
+
+Para desabilitar completamente a ferramenta `exec`, defina `enabled` como `false`:
+
+**Via arquivo de configuração:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via variável de ambiente:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Nota:** Quando desabilitada, o agent não poderá executar comandos shell. Isso também afeta a capacidade da ferramenta Cron de executar comandos shell agendados.
+
 ### Funcionalidade

 - **`enable_deny_patterns`**: Defina como `false` para desabilitar completamente os padrões de bloqueio de comandos perigosos padrão
@ -175,7 +198,6 @@ Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa
 | `env_file` | string | não         | Caminho para arquivo de ambiente para processo stdio |
 | `url`      | string | sse/http    | URL do endpoint para transporte `sse`/`http` |
 | `headers`  | object | não         | Cabeçalhos HTTP para transporte `sse`/`http` |
-| `timeout`  | int    | não         | Tempo limite de chamada de ferramenta em segundos (padrão: 60) |

 ### Comportamento do transporte

@ -224,8 +246,7 @@ Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -331,6 +352,7 @@ Todas as opções de configuração podem ser substituídas via variáveis de am
 Por exemplo:

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@ -68,9 +68,32 @@ The exec tool is used to execute shell commands.

 | Config                 | Type  | Default | Description                                |
 |------------------------|-------|---------|--------------------------------------------|
+| `enabled`              | bool  | true    | Enable the exec tool                        |
 | `enable_deny_patterns` | bool  | true    | Enable default dangerous command blocking  |
 | `custom_deny_patterns` | array | []      | Custom deny patterns (regular expressions) |

+### Disabling the Exec Tool
+
+To completely disable the `exec` tool, set `enabled` to `false`:
+
+**Via config file:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via environment variable:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note:** When disabled, the agent will not be able to execute shell commands. This also affects the Cron tool's ability to run scheduled shell commands.
+
 ### Functionality

 - **`enable_deny_patterns`**: Set to `false` to completely disable the default dangerous command blocking patterns
@ -158,7 +181,7 @@ and injected into the context for a configured number of turns (`ttl`).

 | Config               | Type | Default | Description                                                                                                                       |
 |----------------------|------|---------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `enabled`            | bool | false   | If true, MCP tools are hidden and loaded on-demand via search. If false, all tools are loaded                                     |
+| `enabled`            | bool | false   | Global default: if `true`, all MCP tools are hidden and loaded on-demand via search; if `false`, all tools are loaded into context. Individual servers can override this with the per-server `deferred` field. |
 | `ttl`                | int  | 5       | Number of conversational turns a discovered tool remains unlocked                                                                 |
 | `max_search_results` | int  | 5       | Maximum number of tools returned per search query                                                                                 |
 | `use_bm25`           | bool | true    | Enable the natural language/keyword search tool (`tool_search_tool_bm25`). **Warning**: consumes more resources than regex search |
@ -169,17 +192,17 @@ and injected into the context for a configured number of turns (`ttl`).

 ### Per-Server Config

-| Config     | Type   | Required | Description                                |
-|------------|--------|----------|--------------------------------------------|
-| `enabled`  | bool   | yes      | Enable this MCP server                     |
-| `type`     | string | no       | Transport type: `stdio`, `sse`, `http`     |
-| `command`  | string | stdio    | Executable command for stdio transport     |
-| `args`     | array  | no       | Command arguments for stdio transport      |
-| `env`      | object | no       | Environment variables for stdio process    |
-| `env_file` | string | no       | Path to environment file for stdio process |
-| `url`      | string | sse/http | Endpoint URL for `sse`/`http` transport    |
-| `headers`  | object | no       | HTTP headers for `sse`/`http` transport    |
-| `timeout`  | int    | no       | Tool call timeout in seconds (default: 60) |
+| Config     | Type    | Required | Description                                                                                                                                                     |
+|------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`  | bool    | yes      | Enable this MCP server                                                                                                                                          |
+| `deferred` | bool    | no       | Override deferred mode for this server only. `true` = tools are hidden and discoverable via search; `false` = tools are always visible in context. When omitted, the global `discovery.enabled` value applies. |
+| `type`     | string  | no       | Transport type: `stdio`, `sse`, `http`                                                                                                                          |
+| `command`  | string  | stdio    | Executable command for stdio transport                                                                                                                          |
+| `args`     | array   | no       | Command arguments for stdio transport                                                                                                                           |
+| `env`      | object  | no       | Environment variables for stdio process                                                                                                                         |
+| `env_file` | string  | no       | Path to environment file for stdio process                                                                                                                      |
+| `url`      | string  | sse/http | Endpoint URL for `sse`/`http` transport                                                                                                                         |
+| `headers`  | object  | no       | HTTP headers for `sse`/`http` transport                                                                                                                         |

 ### Transport Behavior

@ -228,8 +251,7 @@ and injected into the context for a configured number of turns (`ttl`).
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -293,6 +315,50 @@ dynamically only when requested by the user.*
 }
 ```

+#### 4) Mixed setup: per-server deferred override
+
+*Discovery is enabled globally, but `filesystem` is pinned as always-visible while `context7` follows the global
+default (deferred). `aws` explicitly opts in to deferred mode even though it is the same as the global default.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true
+      },
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+          "deferred": false
+        },
+        "context7": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@upstash/context7-mcp"]
+        },
+        "aws": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "aws-mcp-server"],
+          "deferred": true
+        }
+      }
+    }
+  }
+}
+```
+
+> **Tip:** `deferred` on a per-server basis is independent of `discovery.enabled`. You can keep
+> `discovery.enabled: false` globally (all tools visible by default) and still mark individual
+> high-volume servers as `"deferred": true` to avoid polluting the context with their tools.
+
 ## Skills Tool

 The skills tool configures skill discovery and installation via registries like ClawHub.
@ -336,6 +402,7 @@ All configuration options can be overridden via environment variables with the f
 For example:

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/docs/vi/chat-apps.md
+++ b/docs/vi/chat-apps.md
@ -410,7 +410,8 @@ picoclaw gateway
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
-      "welcome_message": "Hello! How can I help you?"
+      "welcome_message": "Hello! How can I help you?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
 }
--- a/docs/vi/configuration.md
+++ b/docs/vi/configuration.md
@ -42,13 +42,15 @@ PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định:
 ├── state/            # Trạng thái bền vững (kênh cuối, v.v.)
 ├── cron/             # Cơ sở dữ liệu tác vụ lên lịch
 ├── skills/           # Skill tùy chỉnh
-├── AGENTS.md         # Hướng dẫn hành vi agent
+├── AGENT.md          # Hướng dẫn hành vi agent
 ├── HEARTBEAT.md      # Prompt tác vụ định kỳ (kiểm tra mỗi 30 phút)
 ├── IDENTITY.md       # Danh tính agent
 ├── SOUL.md           # Linh hồn agent
 └── USER.md           # Tùy chọn người dùng
 ```

+> **Lưu ý:** Các thay đổi đối với `AGENT.md`, `SOUL.md`, `USER.md` và `memory/MEMORY.md` được tự động phát hiện trong thời gian chạy thông qua theo dõi thời gian sửa đổi file (mtime). **Không cần khởi động lại gateway** sau khi chỉnh sửa các file này — agent sẽ tải nội dung mới vào yêu cầu tiếp theo.
+
 ### Nguồn Skill

 Mặc định, skill được tải từ:
--- a/docs/vi/tools_configuration.md
+++ b/docs/vi/tools_configuration.md
@ -70,9 +70,32 @@ Công cụ exec được sử dụng để thực thi các lệnh shell.

 | Cấu hình               | Kiểu  | Mặc định | Mô tả                                         |
 |--------------------------|-------|----------|------------------------------------------------|
+| `enabled`                | bool  | true     | Bật công cụ exec                             |
 | `enable_deny_patterns`   | bool  | true     | Bật chặn lệnh nguy hiểm mặc định             |
 | `custom_deny_patterns`   | array | []       | Mẫu từ chối tùy chỉnh (biểu thức chính quy)  |

+### Vô hiệu hóa Công cụ Exec
+
+Để hoàn toàn vô hiệu hóa công cụ `exec`, đặt `enabled` thành `false`:
+
+**Qua tệp cấu hình:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Qua biến môi trường:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Lưu ý:** Khi bị vô hiệu hóa, agent sẽ không thể thực thi lệnh shell. Điều này cũng ảnh hưởng đến khả năng chạy lệnh shell theo lịch của công cụ Cron.
+
 ### Chức năng

 - **`enable_deny_patterns`**: Đặt thành `false` để tắt hoàn toàn các mẫu chặn lệnh nguy hiểm mặc định
@ -175,7 +198,6 @@ Thay vì tải tất cả các công cụ, LLM được cung cấp một công c
 | `env_file` | string | không    | Đường dẫn đến tệp môi trường cho tiến trình stdio |
 | `url`      | string | sse/http | URL endpoint cho truyền tải `sse`/`http`  |
 | `headers`  | object | không    | Header HTTP cho truyền tải `sse`/`http`   |
-| `timeout`  | int    | không    | Thời gian chờ gọi công cụ tính bằng giây (mặc định: 60) |

 ### Hành vi truyền tải

@ -224,8 +246,7 @@ Thay vì tải tất cả các công cụ, LLM được cung cấp một công c
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -331,6 +352,7 @@ Tất cả các tùy chọn cấu hình có thể được ghi đè qua biến m
 Ví dụ:

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/docs/zh/chat-apps.md
+++ b/docs/zh/chat-apps.md
@ -510,7 +510,8 @@ picoclaw gateway
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
-      "welcome_message": "你好！有什么可以帮你的？"
+      "welcome_message": "你好！有什么可以帮你的？",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
    }
  }
 }
--- a/docs/zh/configuration.md
+++ b/docs/zh/configuration.md
@ -42,13 +42,15 @@ PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/work
 ├── state/            # 持久化状态 (最后一次频道等)
 ├── cron/             # 定时任务数据库
 ├── skills/           # 自定义技能
-├── AGENTS.md         # Agent 行为指南
+├── AGENT.md          # Agent 行为指南
 ├── HEARTBEAT.md      # 周期性任务提示词 (每 30 分钟检查一次)
 ├── IDENTITY.md       # Agent 身份设定
 ├── SOUL.md           # Agent 灵魂/性格
 └── USER.md           # 用户偏好
 ```

+> **提示：** 对 `AGENT.md`、`SOUL.md`、`USER.md` 和 `memory/MEMORY.md` 的修改会通过文件修改时间（mtime）在运行时自动检测。**无需重启 gateway**，Agent 将在下一次请求时自动加载最新内容。
+
 ### 技能来源 (Skill Sources)

 默认情况下，技能会按以下顺序加载：
--- a/docs/zh/tools_configuration.md
+++ b/docs/zh/tools_configuration.md
@ -70,9 +70,32 @@ Exec 工具用于执行 shell 命令。

 | 配置项                 | 类型  | 默认值 | 描述                           |
 |------------------------|-------|--------|--------------------------------|
+| `enabled`              | bool  | true   | 启用 exec 工具                 |
 | `enable_deny_patterns` | bool  | true   | 启用默认的危险命令拦截         |
 | `custom_deny_patterns` | array | []     | 自定义拒绝模式（正则表达式）   |

+### 禁用 Exec 工具
+
+要完全禁用 `exec` 工具，请将 `enabled` 设置为 `false`：
+
+**通过配置文件：**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**通过环境变量：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 禁用后，代理将无法执行 shell 命令。这也会影响 Cron 工具运行计划 shell 命令的能力。
+
 ### 功能说明

 - **`enable_deny_patterns`**：设为 `false` 可完全禁用默认的危险命令拦截模式
@ -175,7 +198,6 @@ LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用
 | `env_file` | string | 否       | stdio 进程的环境文件路径           |
 | `url`      | string | sse/http | `sse`/`http` 传输的端点 URL        |
 | `headers`  | object | 否       | `sse`/`http` 传输的 HTTP 头        |
-| `timeout`  | int    | 否       | 工具调用超时时间（秒，默认: 60）   |

 ### 传输行为

@ -224,8 +246,7 @@ LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
-          },
-          "timeout": 120
+          }
        }
      }
    }
@ -331,6 +352,7 @@ Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
 例如：

 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
 - `PICOCLAW_TOOLS_MCP_ENABLED=true`
--- a/go.mod
+++ b/go.mod
@ -1,6 +1,6 @@
 module github.com/sipeed/picoclaw

-go 1.25.7
+go 1.25.8

 require (
 	fyne.io/systray v1.12.0
@ -8,7 +8,7 @@ require (
 	github.com/anthropics/anthropic-sdk-go v1.26.0
 	github.com/bwmarrin/discordgo v0.29.0
 	github.com/caarlos0/env/v11 v11.4.0
-	github.com/ergochat/irc-go v0.5.0
+	github.com/ergochat/irc-go v0.6.0
 	github.com/ergochat/readline v0.1.3
 	github.com/gdamore/tcell/v2 v2.13.8
 	github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab
@ -17,7 +17,7 @@ require (
 	github.com/h2non/filetype v1.1.3
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
 	github.com/mdp/qrterminal/v3 v3.2.1
-	github.com/modelcontextprotocol/go-sdk v1.3.1
+	github.com/modelcontextprotocol/go-sdk v1.4.1
 	github.com/mymmrac/telego v1.7.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/openai/openai-go/v3 v3.22.0
@ -33,12 +33,12 @@ require (
 	golang.org/x/time v0.14.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
-	maunium.net/go/mautrix v0.26.3
+	maunium.net/go/mautrix v0.26.4
 	modernc.org/sqlite v1.46.1
 )

 require (
-	filippo.io/edwards25519 v1.1.1 // indirect
+	filippo.io/edwards25519 v1.2.0 // indirect
 	github.com/beeper/argo-go v1.1.2 // indirect
 	github.com/coder/websocket v1.8.14 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
@ -51,17 +51,17 @@ require (
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
-	github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 // indirect
+	github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/segmentio/asm v1.1.3 // indirect
-	github.com/segmentio/encoding v0.5.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/vektah/gqlparser/v2 v2.5.27 // indirect
 	go.mau.fi/libsignal v0.2.1 // indirect
-	go.mau.fi/util v0.9.6 // indirect
-	golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a // indirect
+	go.mau.fi/util v0.9.7 // indirect
+	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
 	golang.org/x/text v0.35.0 // indirect
 	modernc.org/libc v1.67.6 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
@ -93,7 +93,7 @@ require (
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/arch v0.24.0 // indirect
 	golang.org/x/crypto v0.49.0
-	golang.org/x/net v0.51.0
+	golang.org/x/net v0.52.0
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 )
--- a/go.sum
+++ b/go.sum
@ -1,6 +1,6 @@
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
-filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
-filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 fyne.io/systray v1.12.0 h1:CA1Kk0e2zwFlxtc02L3QFSiIbxJ/P0n582YrZHT7aTM=
 fyne.io/systray v1.12.0/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
@ -46,8 +46,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/elliotchance/orderedmap/v3 v3.1.0 h1:j4DJ5ObEmMBt/lcwIecKcoRxIQUEnw0L804lXYDt/pg=
 github.com/elliotchance/orderedmap/v3 v3.1.0/go.mod h1:G+Hc2RwaZvJMcS4JpGCOyViCnGeKf0bTYCGTO4uhjSo=
-github.com/ergochat/irc-go v0.5.0 h1:woQ1RS9YbfgqPgSpPBBQeczXGIGzR0aC7dEgk469fTw=
-github.com/ergochat/irc-go v0.5.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
+github.com/ergochat/irc-go v0.6.0 h1:Y0AGV76aeihJfCtLaQh+OyJKFiKGrYC0VTkeMZ6XW28=
+github.com/ergochat/irc-go v0.6.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
 github.com/ergochat/readline v0.1.3 h1:/DytGTmwdUJcLAe3k3VJgowh5vNnsdifYT6uVaf4pSo=
 github.com/ergochat/readline v0.1.3/go.mod h1:o3ux9QLHLm77bq7hDB21UTm6HlV2++IPDMfIfKDuOgY=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
@ -70,8 +70,8 @@ github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
 github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
-github.com/golang-jwt/jwt/v5 v5.2.2 h1:Rl4B7itRWVtYIHFrSNd7vhTiz9UpLdi6gZhZ3wEeDy8=
-github.com/golang-jwt/jwt/v5 v5.2.2/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
 github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
@ -140,8 +140,8 @@ github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp
 github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
 github.com/mdp/qrterminal/v3 v3.2.1 h1:6+yQjiiOsSuXT5n9/m60E54vdgFsw0zhADHhHLrFet4=
 github.com/mdp/qrterminal/v3 v3.2.1/go.mod h1:jOTmXvnBsMy5xqLniO0R++Jmjs2sTm9dFSuQ5kpz/SU=
-github.com/modelcontextprotocol/go-sdk v1.3.1 h1:TfqtNKOIWN4Z1oqmPAiWDC2Jq7K9OdJaooe0teoXASI=
-github.com/modelcontextprotocol/go-sdk v1.3.1/go.mod h1:DgVX498dMD8UJlseK1S5i1T4tFz2fkBk4xogC3D15nw=
+github.com/modelcontextprotocol/go-sdk v1.4.1 h1:M4x9GyIPj+HoIlHNGpK2hq5o3BFhC+78PkEaldQRphc=
+github.com/modelcontextprotocol/go-sdk v1.4.1/go.mod h1:Bo/mS87hPQqHSRkMv4dQq1XCu6zv4INdXnFZabkNU6s=
 github.com/mymmrac/telego v1.7.0 h1:yRO/l00tFGG4nY66ufUKb4ARqv7qx9+LsjQv/b0NEyo=
 github.com/mymmrac/telego v1.7.0/go.mod h1:pdLV346EgVuq7Xrh3kMggeBiazeHhsdEoK0RTEOPXRM=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
@ -158,8 +158,8 @@ github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv
 github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/openai/openai-go/v3 v3.22.0 h1:6MEoNoV8sbjOVmXdvhmuX3BjVbVdcExbVyGixiyJ8ys=
 github.com/openai/openai-go/v3 v3.22.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 h1:KPpdlQLZcHfTMQRi6bFQ7ogNO0ltFT4PmtwTLW4W+14=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
+github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 h1:rh2lKw/P/EqHa724vYH2+VVQ1YnW4u6EOXl0PMAovZE=
+github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@ -179,8 +179,8 @@ github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
 github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
-github.com/segmentio/encoding v0.5.3 h1:OjMgICtcSFuNvQCdwqMCv9Tg7lEOXGwm1J5RPQccx6w=
-github.com/segmentio/encoding v0.5.3/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
 github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
 github.com/slack-go/slack v0.17.3 h1:zV5qO3Q+WJAQ/XwbGfNFrRMaJ5T/naqaonyPV/1TP4g=
@ -235,8 +235,8 @@ github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9dec
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.mau.fi/libsignal v0.2.1 h1:vRZG4EzTn70XY6Oh/pVKrQGuMHBkAWlGRC22/85m9L0=
 go.mau.fi/libsignal v0.2.1/go.mod h1:iVvjrHyfQqWajOUaMEsIfo3IqgVMrhWcPiiEzk7NgoU=
-go.mau.fi/util v0.9.6 h1:2nsvxm49KhI3wrFltr0+wSUBlnQ4CMtykuELjpIU+ts=
-go.mau.fi/util v0.9.6/go.mod h1:sIJpRH7Iy5Ad1SBuxQoatxtIeErgzxCtjd/2hCMkYMI=
+go.mau.fi/util v0.9.7 h1:AWGNbJfz1zRcQOKeOEYhKUG2fT+/26Gy6kyqcH8tnBg=
+go.mau.fi/util v0.9.7/go.mod h1:5T2f3ZWZFAGgmFwg3dGw7YK6kIsb9lryDzvynoR98pE=
 go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4 h1:hsmlwsM+VqfF70cpdZEeIUKer2XWCQmQPK0u0tHy3ZQ=
 go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4/go.mod h1:mXCRFyPEPn4jqWz6Afirn8vY7DpHCPnlKq6I2cWwFHM=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
@ -252,14 +252,14 @@ golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5y
 golang.org/x/crypto v0.16.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
 golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
 golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
-golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a h1:ovFr6Z0MNmU7nH8VaX5xqw+05ST2uO1exVfZPVqRC5o=
-golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
-golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
@ -273,8 +273,8 @@ golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
-golang.org/x/net v0.51.0 h1:94R/GTO7mt3/4wIKpcR5gkGmRLOuE/2hNGeWq/GBIFo=
-golang.org/x/net v0.51.0/go.mod h1:aamm+2QF5ogm02fjy5Bb7CQ0WMt1/WVM7FtyaTLlA9Y=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
 golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
@ -334,8 +334,8 @@ golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4f
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
-golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@ -365,8 +365,8 @@ gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-maunium.net/go/mautrix v0.26.3 h1:tWZih6Vjw0qGTWuPmg9JUrQPzViTNDPGQLVc5UXC4nk=
-maunium.net/go/mautrix v0.26.3/go.mod h1:v5ZdDoCwUpNqEj5OrhEoUa3L1kEddKPaAya9TgGXN38=
+maunium.net/go/mautrix v0.26.4 h1:enHSnkf0L2V9+VnfJfNhKSReSW6pBKS/x3Su+v+Vovs=
+maunium.net/go/mautrix v0.26.4/go.mod h1:YWw8NWTszsbyFAznboicBObwHPgTSLcuTbVX2kY7U2M=
 modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
 modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
 modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=
--- a/pkg/agent/loop_mcp.go
+++ b/pkg/agent/loop_mcp.go
@ -11,6 +11,7 @@ import (
 	"fmt"
 	"sync"

+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/mcp"
 	"github.com/sipeed/picoclaw/pkg/tools"
@ -111,6 +112,12 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {

 		for serverName, conn := range servers {
 			uniqueTools += len(conn.Tools)
+
+			// Determine whether this server's tools should be deferred (hidden).
+			// Per-server "deferred" field takes precedence over the global Discovery.Enabled.
+			serverCfg := al.cfg.Tools.MCP.Servers[serverName]
+			registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
+
 			for _, tool := range conn.Tools {
 				for _, agentID := range agentIDs {
 					agent, ok := al.registry.GetAgent(agentID)
@ -120,7 +127,7 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {

 					mcpTool := tools.NewMCPTool(mcpManager, serverName, tool)

-					if al.cfg.Tools.MCP.Discovery.Enabled {
+					if registerAsHidden {
 						agent.Tools.RegisterHidden(mcpTool)
 					} else {
 						agent.Tools.Register(mcpTool)
@ -133,6 +140,7 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
 							"server":   serverName,
 							"tool":     tool.Name,
 							"name":     mcpTool.Name(),
+							"deferred": registerAsHidden,
 						})
 				}
 			}
@ -198,3 +206,18 @@ func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {

 	return al.mcp.getInitErr()
 }
+
+// serverIsDeferred reports whether an MCP server's tools should be registered
+// as hidden (deferred/discovery mode).
+//
+// The per-server Deferred field takes precedence over the global discoveryEnabled
+// default. When Deferred is nil, discoveryEnabled is used as the fallback.
+func serverIsDeferred(discoveryEnabled bool, serverCfg config.MCPServerConfig) bool {
+	if !discoveryEnabled {
+		return false
+	}
+	if serverCfg.Deferred != nil {
+		return *serverCfg.Deferred
+	}
+	return true
+}
--- a/pkg/agent/loop_mcp_test.go
+++ b/pkg/agent/loop_mcp_test.go
@ -0,0 +1,75 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func boolPtr(b bool) *bool { return &b }
+
+func TestServerIsDeferred(t *testing.T) {
+	tests := []struct {
+		name             string
+		discoveryEnabled bool
+		serverDeferred   *bool
+		want             bool
+	}{
+		// --- global false always wins: per-server deferred is ignored ---
+		{
+			name:             "global false: per-server deferred=true is ignored",
+			discoveryEnabled: false,
+			serverDeferred:   boolPtr(true),
+			want:             false,
+		},
+		{
+			name:             "global false: per-server deferred=false stays false",
+			discoveryEnabled: false,
+			serverDeferred:   boolPtr(false),
+			want:             false,
+		},
+		// --- global true: per-server override applies ---
+		{
+			name:             "global true: per-server deferred=false opts out",
+			discoveryEnabled: true,
+			serverDeferred:   boolPtr(false),
+			want:             false,
+		},
+		{
+			name:             "global true: per-server deferred=true stays true",
+			discoveryEnabled: true,
+			serverDeferred:   boolPtr(true),
+			want:             true,
+		},
+		// --- no per-server override: fall back to global ---
+		{
+			name:             "no per-server field, global discovery enabled",
+			discoveryEnabled: true,
+			serverDeferred:   nil,
+			want:             true,
+		},
+		{
+			name:             "no per-server field, global discovery disabled",
+			discoveryEnabled: false,
+			serverDeferred:   nil,
+			want:             false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			serverCfg := config.MCPServerConfig{Deferred: tt.serverDeferred}
+			got := serverIsDeferred(tt.discoveryEnabled, serverCfg)
+			if got != tt.want {
+				t.Errorf("serverIsDeferred(discoveryEnabled=%v, deferred=%v) = %v, want %v",
+					tt.discoveryEnabled, tt.serverDeferred, got, tt.want)
+			}
+		})
+	}
+}
--- a/pkg/agent/model_resolution.go
+++ b/pkg/agent/model_resolution.go
@ -0,0 +1,97 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func buildModelListResolver(cfg *config.Config) func(raw string) (string, bool) {
+	ensureProtocol := func(model string) string {
+		model = strings.TrimSpace(model)
+		if model == "" {
+			return ""
+		}
+		if strings.Contains(model, "/") {
+			return model
+		}
+		return "openai/" + model
+	}
+
+	return func(raw string) (string, bool) {
+		raw = strings.TrimSpace(raw)
+		if raw == "" || cfg == nil {
+			return "", false
+		}
+
+		if mc, err := cfg.GetModelConfig(raw); err == nil && mc != nil && strings.TrimSpace(mc.Model) != "" {
+			return ensureProtocol(mc.Model), true
+		}
+
+		for i := range cfg.ModelList {
+			fullModel := strings.TrimSpace(cfg.ModelList[i].Model)
+			if fullModel == "" {
+				continue
+			}
+			if fullModel == raw {
+				return ensureProtocol(fullModel), true
+			}
+			_, modelID := providers.ExtractProtocol(fullModel)
+			if modelID == raw {
+				return ensureProtocol(fullModel), true
+			}
+		}
+
+		return "", false
+	}
+}
+
+func resolveModelCandidates(
+	cfg *config.Config,
+	defaultProvider string,
+	primary string,
+	fallbacks []string,
+) []providers.FallbackCandidate {
+	return providers.ResolveCandidatesWithLookup(
+		providers.ModelConfig{
+			Primary:   primary,
+			Fallbacks: fallbacks,
+		},
+		defaultProvider,
+		buildModelListResolver(cfg),
+	)
+}
+
+func resolvedCandidateModel(candidates []providers.FallbackCandidate, fallback string) string {
+	if len(candidates) > 0 && strings.TrimSpace(candidates[0].Model) != "" {
+		return candidates[0].Model
+	}
+	return fallback
+}
+
+func resolvedCandidateProvider(candidates []providers.FallbackCandidate, fallback string) string {
+	if len(candidates) > 0 && strings.TrimSpace(candidates[0].Provider) != "" {
+		return candidates[0].Provider
+	}
+	return fallback
+}
+
+func resolvedModelConfig(cfg *config.Config, modelName, workspace string) (*config.ModelConfig, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("config is nil")
+	}
+
+	modelCfg, err := cfg.GetModelConfig(strings.TrimSpace(modelName))
+	if err != nil {
+		return nil, err
+	}
+
+	clone := *modelCfg
+	if clone.Workspace == "" {
+		clone.Workspace = workspace
+	}
+
+	return &clone, nil
+}
--- a/pkg/channels/feishu/common.go
+++ b/pkg/channels/feishu/common.go
@ -84,3 +84,64 @@ func stripMentionPlaceholders(content string, mentions []*larkim.MentionEvent) s
 	content = mentionPlaceholderRegex.ReplaceAllString(content, "")
 	return strings.TrimSpace(content)
 }
+
+// extractCardImageKeys recursively extracts all image keys from a Feishu interactive card.
+// Image keys are used to download images from Feishu API.
+// Returns two slices: Feishu-hosted keys and external URLs.
+func extractCardImageKeys(rawContent string) (feishuKeys []string, externalURLs []string) {
+	if rawContent == "" {
+		return nil, nil
+	}
+
+	var card map[string]any
+	if err := json.Unmarshal([]byte(rawContent), &card); err != nil {
+		return nil, nil
+	}
+
+	extractImageKeysRecursive(card, &feishuKeys, &externalURLs)
+	return feishuKeys, externalURLs
+}
+
+// isExternalURL returns true if the string is an external HTTP/HTTPS URL.
+func isExternalURL(s string) bool {
+	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+// extractImageKeysRecursive traverses card structure to find all image keys.
+// Collects both Feishu-hosted keys and external URLs separately.
+func extractImageKeysRecursive(v any, feishuKeys, externalURLs *[]string) {
+	switch val := v.(type) {
+	case map[string]any:
+		// Check if this is an img element
+		if tag, ok := val["tag"].(string); ok {
+			switch tag {
+			case "img":
+				// Try img_key first (always Feishu-hosted)
+				if imgKey, ok := val["img_key"].(string); ok && imgKey != "" {
+					*feishuKeys = append(*feishuKeys, imgKey)
+				}
+				// Check src - could be Feishu key or external URL
+				if src, ok := val["src"].(string); ok && src != "" {
+					if isExternalURL(src) {
+						*externalURLs = append(*externalURLs, src)
+					} else {
+						*feishuKeys = append(*feishuKeys, src)
+					}
+				}
+			case "icon":
+				// Icon elements use icon_key
+				if iconKey, ok := val["icon_key"].(string); ok && iconKey != "" {
+					*feishuKeys = append(*feishuKeys, iconKey)
+				}
+			}
+		}
+		// Recurse into all nested structures
+		for _, child := range val {
+			extractImageKeysRecursive(child, feishuKeys, externalURLs)
+		}
+	case []any:
+		for _, item := range val {
+			extractImageKeysRecursive(item, feishuKeys, externalURLs)
+		}
+	}
+}
--- a/pkg/channels/feishu/common_test.go
+++ b/pkg/channels/feishu/common_test.go
@ -290,3 +290,119 @@ func TestStripMentionPlaceholders(t *testing.T) {
 		})
 	}
 }
+
+func TestExtractCardImageKeys(t *testing.T) {
+	tests := []struct {
+		name             string
+		content          string
+		wantFeishuKeys   []string
+		wantExternalURLs []string
+	}{
+		{
+			name:             "empty content",
+			content:          "",
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "invalid JSON",
+			content:          "not json",
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "card with no images",
+			content:          `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"text"}]}}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "single image with img_key",
+			content:          `{"elements":[{"tag":"img","img_key":"img_abc123"}]}`,
+			wantFeishuKeys:   []string{"img_abc123"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "single image with src as Feishu key",
+			content:          `{"elements":[{"tag":"img","src":"img_xyz789"}]}`,
+			wantFeishuKeys:   []string{"img_xyz789"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "multiple images",
+			content:          `{"elements":[{"tag":"img","img_key":"img_1"},{"tag":"div","text":{"content":"text"}},{"tag":"img","img_key":"img_2"}]}`,
+			wantFeishuKeys:   []string{"img_1", "img_2"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "nested image in columns",
+			content:          `{"elements":[{"tag":"div","columns":[{"tag":"img","img_key":"img_col1"},{"tag":"img","img_key":"img_col2"}]}]}`,
+			wantFeishuKeys:   []string{"img_col1", "img_col2"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "image in action",
+			content:          `{"elements":[{"tag":"action","actions":[{"tag":"img","img_key":"img_action"}]}]}`,
+			wantFeishuKeys:   []string{"img_action"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "icon element",
+			content:          `{"elements":[{"tag":"icon","icon_key":"icon_123"}]}`,
+			wantFeishuKeys:   []string{"icon_123"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "complex card with text and images",
+			content:          `{"header":{"title":{"content":"Title"}},"elements":[{"tag":"div","text":{"content":"Description"}},{"tag":"img","img_key":"img_main"}]}`,
+			wantFeishuKeys:   []string{"img_main"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "external URL in src",
+			content:          `{"elements":[{"tag":"img","src":"https://example.com/image.png"}]}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: []string{"https://example.com/image.png"},
+		},
+		{
+			name:             "mixed Feishu keys and external URLs",
+			content:          `{"elements":[{"tag":"img","img_key":"img_feishu"},{"tag":"img","src":"https://cdn.example.com/external.jpg"},{"tag":"img","src":"img_another"}]}`,
+			wantFeishuKeys:   []string{"img_feishu", "img_another"},
+			wantExternalURLs: []string{"https://cdn.example.com/external.jpg"},
+		},
+		{
+			name:             "multiple external URLs",
+			content:          `{"elements":[{"tag":"img","src":"https://a.com/1.png"},{"tag":"img","src":"http://b.com/2.jpg"}]}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: []string{"https://a.com/1.png", "http://b.com/2.jpg"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotFeishuKeys, gotExternalURLs := extractCardImageKeys(tt.content)
+
+			// Compare Feishu keys
+			if len(gotFeishuKeys) != len(tt.wantFeishuKeys) {
+				t.Errorf("extractCardImageKeys() feishuKeys = %v, want %v", gotFeishuKeys, tt.wantFeishuKeys)
+				return
+			}
+			for i, v := range gotFeishuKeys {
+				if v != tt.wantFeishuKeys[i] {
+					t.Errorf("extractCardImageKeys() feishuKeys[%d] = %q, want %q", i, v, tt.wantFeishuKeys[i])
+				}
+			}
+
+			// Compare external URLs
+			if len(gotExternalURLs) != len(tt.wantExternalURLs) {
+				t.Errorf("extractCardImageKeys() externalURLs = %v, want %v", gotExternalURLs, tt.wantExternalURLs)
+				return
+			}
+			for i, v := range gotExternalURLs {
+				if v != tt.wantExternalURLs[i] {
+					t.Errorf("extractCardImageKeys() externalURLs[%d] = %q, want %q", i, v, tt.wantExternalURLs[i])
+				}
+			}
+		})
+	}
+}
--- a/pkg/channels/feishu/feishu_64.go
+++ b/pkg/channels/feishu/feishu_64.go
@ -11,6 +11,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
 	"sync"
 	"sync/atomic"

@ -129,6 +130,7 @@ func (c *FeishuChannel) Stop(ctx context.Context) error {
 }

 // Send sends a message using Interactive Card format for markdown rendering.
+// Falls back to plain text message if card sending fails (e.g., table limit exceeded).
 func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
 		return channels.ErrNotRunning
@ -141,9 +143,38 @@ func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 	// Build interactive card with markdown content
 	cardContent, err := buildMarkdownCard(msg.Content)
 	if err != nil {
-		return fmt.Errorf("feishu send: card build failed: %w", err)
+		// If card build fails, fall back to plain text
+		return c.sendText(ctx, msg.ChatID, msg.Content)
 	}
-	return c.sendCard(ctx, msg.ChatID, cardContent)
+
+	// First attempt: try sending as interactive card
+	err = c.sendCard(ctx, msg.ChatID, cardContent)
+	if err == nil {
+		return nil
+	}
+
+	// Check if error is due to card table limit (error code 11310)
+	// See: https://open.feishu.cn/document/server-docs/im-api/message-content-description/create_json
+	errMsg := err.Error()
+	isCardLimitError := strings.Contains(errMsg, "11310")
+
+	if isCardLimitError {
+		logger.WarnCF("feishu", "Card send failed (table limit), falling back to text message", map[string]any{
+			"chat_id": msg.ChatID,
+			"error":   errMsg,
+		})
+
+		// Second attempt: fall back to plain text message
+		textErr := c.sendText(ctx, msg.ChatID, msg.Content)
+		if textErr == nil {
+			return nil
+		}
+		// If text also fails, return the text error
+		return textErr
+	}
+
+	// For other errors, return the original card error
+	return err
 }

 // EditMessage implements channels.MessageEditor.
@ -393,6 +424,15 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.
 		mediaRefs = c.downloadInboundMedia(ctx, chatID, messageID, messageType, rawContent, store)
 	}

+	// For interactive cards, pass external image URLs via media refs.
+	// Keep content as valid raw JSON for downstream parsing.
+	if messageType == larkim.MsgTypeInteractive {
+		_, externalURLs := extractCardImageKeys(rawContent)
+		if len(externalURLs) > 0 {
+			mediaRefs = append(mediaRefs, externalURLs...)
+		}
+	}
+
 	// Append media tags to content (like Telegram does)
 	content = appendMediaTags(content, messageType, mediaRefs)

@ -528,6 +568,10 @@ func extractContent(messageType, rawContent string) string {
 		// Pass raw JSON to LLM — structured rich text is more informative than flattened plain text
 		return rawContent

+	case larkim.MsgTypeInteractive:
+		// Pass raw JSON to LLM — structured card is more informative than flattened text
+		return rawContent
+
 	case larkim.MsgTypeImage:
 		// Image messages don't have text content
 		return ""
@ -565,6 +609,18 @@ func (c *FeishuChannel) downloadInboundMedia(
 			refs = append(refs, ref)
 		}

+	case larkim.MsgTypeInteractive:
+		// Extract and download images embedded in interactive cards
+		feishuKeys, _ := extractCardImageKeys(rawContent)
+		// Download Feishu-hosted images via API
+		for _, imageKey := range feishuKeys {
+			ref := c.downloadResource(ctx, messageID, imageKey, "image", ".jpg", store, scope)
+			if ref != "" {
+				refs = append(refs, ref)
+			}
+		}
+		// External URLs are passed directly to LLM, not downloaded
+
 	case larkim.MsgTypeFile, larkim.MsgTypeAudio, larkim.MsgTypeMedia:
 		fileKey := extractFileKey(rawContent)
 		if fileKey == "" {
@ -685,11 +741,18 @@ func (c *FeishuChannel) downloadResource(
 }

 // appendMediaTags appends media type tags to content (like Telegram's "[image: photo]").
+// For interactive cards, media tags are not appended because content is raw JSON
+// and appending would produce invalid JSON format.
 func appendMediaTags(content, messageType string, mediaRefs []string) string {
 	if len(mediaRefs) == 0 {
 		return content
 	}

+	// Don't append tags to JSON content (interactive cards) - would produce invalid JSON
+	if messageType == larkim.MsgTypeInteractive {
+		return content
+	}
+
 	var tag string
 	switch messageType {
 	case larkim.MsgTypeImage:
@ -738,6 +801,35 @@ func (c *FeishuChannel) sendCard(ctx context.Context, chatID, cardContent string
 	return nil
 }

+// sendText sends a plain text message to a chat (fallback when card fails).
+func (c *FeishuChannel) sendText(ctx context.Context, chatID, text string) error {
+	content, _ := json.Marshal(map[string]string{"text": text})
+
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeText).
+			Content(string(content)).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Create(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu send text: %w", channels.ErrTemporary)
+	}
+
+	if !resp.Success() {
+		return fmt.Errorf("feishu text api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
+	}
+
+	logger.DebugCF("feishu", "Feishu text message sent (fallback)", map[string]any{
+		"chat_id": chatID,
+	})
+
+	return nil
+}
+
 // sendImage uploads an image and sends it as a message.
 func (c *FeishuChannel) sendImage(ctx context.Context, chatID string, file *os.File) error {
 	// Upload image to get image_key
--- a/pkg/channels/feishu/feishu_64_test.go
+++ b/pkg/channels/feishu/feishu_64_test.go
@ -75,6 +75,24 @@ func TestExtractContent(t *testing.T) {
 			rawContent:  "",
 			want:        "",
 		},
+		{
+			name:        "interactive card returns raw JSON",
+			messageType: "interactive",
+			rawContent:  `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+			want:        `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+		},
+		{
+			name:        "interactive card with complex structure returns raw JSON",
+			messageType: "interactive",
+			rawContent:  `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+			want:        `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+		},
+		{
+			name:        "interactive card invalid JSON returns as-is",
+			messageType: "interactive",
+			rawContent:  `not valid json`,
+			want:        `not valid json`,
+		},
 	}

 	for _, tt := range tests {
@ -151,6 +169,13 @@ func TestAppendMediaTags(t *testing.T) {
 			mediaRefs:   []string{"ref1"},
 			want:        "something [attachment]",
 		},
+		{
+			name:        "interactive card with images returns content unchanged",
+			content:     `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+			messageType: "interactive",
+			mediaRefs:   []string{"ref1"},
+			want:        `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+		},
 	}

 	for _, tt := range tests {
--- a/pkg/channels/manager_channel.go
+++ b/pkg/channels/manager_channel.go
@ -0,0 +1,86 @@
+package channels
+
+import (
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func toChannelHashes(cfg *config.Config) map[string]string {
+	result := make(map[string]string)
+	ch := cfg.Channels
+	// should not be error
+	marshal, _ := json.Marshal(ch)
+	var channelConfig map[string]map[string]any
+	_ = json.Unmarshal(marshal, &channelConfig)
+
+	for key, value := range channelConfig {
+		if !value["enabled"].(bool) {
+			continue
+		}
+		valueBytes, _ := json.Marshal(value)
+		hash := md5.Sum(valueBytes)
+		result[key] = hex.EncodeToString(hash[:])
+	}
+
+	return result
+}
+
+func compareChannels(old, news map[string]string) (added, removed []string) {
+	for key, newHash := range news {
+		if oldHash, ok := old[key]; ok {
+			if newHash != oldHash {
+				removed = append(removed, key)
+				added = append(added, key)
+			}
+		} else {
+			added = append(added, key)
+		}
+	}
+	for key := range old {
+		if _, ok := news[key]; !ok {
+			removed = append(removed, key)
+		}
+	}
+	return added, removed
+}
+
+func toChannelConfig(cfg *config.Config, list []string) (*config.ChannelsConfig, error) {
+	result := &config.ChannelsConfig{}
+	ch := cfg.Channels
+	// should not be error
+	marshal, _ := json.Marshal(ch)
+	var channelConfig map[string]map[string]any
+	_ = json.Unmarshal(marshal, &channelConfig)
+	temp := make(map[string]map[string]any, 0)
+
+	for key, value := range channelConfig {
+		found := false
+		for _, s := range list {
+			if key == s {
+				found = true
+				break
+			}
+		}
+		if !found || !value["enabled"].(bool) {
+			continue
+		}
+		temp[key] = value
+	}
+
+	marshal, err := json.Marshal(temp)
+	if err != nil {
+		logger.Errorf("marshal error: %v", err)
+		return nil, err
+	}
+	err = json.Unmarshal(marshal, result)
+	if err != nil {
+		logger.Errorf("unmarshal error: %v", err)
+		return nil, err
+	}
+
+	return result, nil
+}
--- a/pkg/channels/manager_channel_test.go
+++ b/pkg/channels/manager_channel_test.go
@ -0,0 +1,51 @@
+package channels
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func TestToChannelHashes(t *testing.T) {
+	logger.SetLevel(logger.DEBUG)
+	cfg := config.DefaultConfig()
+	results := toChannelHashes(cfg)
+	assert.Equal(t, 0, len(results))
+	logger.Debugf("results: %v", results)
+	cfg2 := config.DefaultConfig()
+	cfg2.Channels.DingTalk.Enabled = true
+	results2 := toChannelHashes(cfg2)
+	assert.Equal(t, 1, len(results2))
+	logger.Debugf("results2: %v", results2)
+	added, removed := compareChannels(results, results2)
+	assert.EqualValues(t, []string{"dingtalk"}, added)
+	assert.EqualValues(t, []string(nil), removed)
+	cfg3 := config.DefaultConfig()
+	cfg3.Channels.Telegram.Enabled = true
+	results3 := toChannelHashes(cfg3)
+	assert.Equal(t, 1, len(results3))
+	logger.Debugf("results3: %v", results3)
+	added, removed = compareChannels(results2, results3)
+	assert.EqualValues(t, []string{"dingtalk"}, removed)
+	assert.EqualValues(t, []string{"telegram"}, added)
+	cfg3.Channels.Telegram.Token = "114314"
+	results4 := toChannelHashes(cfg3)
+	assert.Equal(t, 1, len(results4))
+	logger.Debugf("results4: %v", results4)
+	added, removed = compareChannels(results3, results4)
+	assert.EqualValues(t, []string{"telegram"}, removed)
+	assert.EqualValues(t, []string{"telegram"}, added)
+	cc, err := toChannelConfig(cfg3, added)
+	assert.NoError(t, err)
+	logger.Debugf("cc: %#v", cc.Telegram)
+	assert.Equal(t, "114314", cc.Telegram.Token)
+	assert.Equal(t, true, cc.Telegram.Enabled)
+	cc, err = toChannelConfig(cfg2, added)
+	assert.NoError(t, err)
+	logger.Debugf("cc: %#v", cc.Telegram)
+	assert.Equal(t, "", cc.Telegram.Token)
+	assert.Equal(t, false, cc.Telegram.Enabled)
+}
--- a/pkg/channels/qq/botgo_logger.go
+++ b/pkg/channels/qq/botgo_logger.go
@ -0,0 +1,41 @@
+package qq
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// botGoLogger preserves useful SDK info logs while demoting noisy heartbeat
+// traffic to DEBUG so long-running QQ sessions do not spam the console.
+type botGoLogger struct {
+	*logger.Logger
+}
+
+func newBotGoLogger(component string) *botGoLogger {
+	return &botGoLogger{Logger: logger.NewLogger(component)}
+}
+
+func (b *botGoLogger) Info(v ...any) {
+	message := fmt.Sprint(v...)
+	if shouldDemoteBotGoInfo(message) {
+		b.Logger.Debug(message)
+		return
+	}
+	b.Logger.Info(message)
+}
+
+func (b *botGoLogger) Infof(format string, v ...any) {
+	message := fmt.Sprintf(format, v...)
+	if shouldDemoteBotGoInfo(message) {
+		b.Logger.Debug(message)
+		return
+	}
+	b.Logger.Info(message)
+}
+
+func shouldDemoteBotGoInfo(message string) bool {
+	return strings.Contains(message, " write Heartbeat message") ||
+		strings.Contains(message, " receive HeartbeatAck message")
+}
--- a/pkg/channels/qq/qq.go
+++ b/pkg/channels/qq/qq.go
@ -2,7 +2,15 @@ package qq

 import (
 	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
 	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path"
+	"path/filepath"
 	"regexp"
 	"strings"
 	"sync"
@ -10,9 +18,10 @@ import (
 	"time"

 	"github.com/tencent-connect/botgo"
+	"github.com/tencent-connect/botgo/constant"
 	"github.com/tencent-connect/botgo/dto"
 	"github.com/tencent-connect/botgo/event"
-	"github.com/tencent-connect/botgo/openapi"
+	"github.com/tencent-connect/botgo/openapi/options"
 	"github.com/tencent-connect/botgo/token"
 	"golang.org/x/oauth2"

@ -21,6 +30,8 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )

 const (
@ -29,16 +40,29 @@ const (
 	dedupMaxSize  = 10000 // hard cap on dedup map entries
 	typingResend  = 8 * time.Second
 	typingSeconds = 10
+	bytesPerMiB   = 1024 * 1024
 )

+type qqAPI interface {
+	WS(ctx context.Context, params map[string]string, body string) (*dto.WebsocketAP, error)
+	PostGroupMessage(
+		ctx context.Context, groupID string, msg dto.APIMessage, opt ...options.Option,
+	) (*dto.Message, error)
+	PostC2CMessage(
+		ctx context.Context, userID string, msg dto.APIMessage, opt ...options.Option,
+	) (*dto.Message, error)
+	Transport(ctx context.Context, method, url string, body any) ([]byte, error)
+}
+
 type QQChannel struct {
 	*channels.BaseChannel
 	config         config.QQConfig
-	api            openapi.OpenAPI
+	api            qqAPI
 	tokenSource    oauth2.TokenSource
 	ctx            context.Context
 	cancel         context.CancelFunc
 	sessionManager botgo.SessionManager
+	downloadFn     func(urlStr, filename string) string

 	// Chat routing: track whether a chatID is group or direct.
 	chatType sync.Map // chatID → "group" | "direct"
@ -78,7 +102,7 @@ func (c *QQChannel) Start(ctx context.Context) error {
 		return fmt.Errorf("QQ app_id and app_secret not configured")
 	}

-	botgo.SetLogger(logger.NewLogger("botgo"))
+	botgo.SetLogger(newBotGoLogger("botgo"))
 	logger.InfoC("qq", "Starting QQ bot (WebSocket mode)")

 	// Reinitialize shutdown signal for clean restart.
@ -199,20 +223,7 @@ func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 		msgToCreate.Content = ""
 	}

-	// Attach passive reply msg_id and msg_seq if available.
-	if v, ok := c.lastMsgID.Load(msg.ChatID); ok {
-		if msgID, ok := v.(string); ok && msgID != "" {
-			msgToCreate.MsgID = msgID
-
-			// Increment msg_seq atomically for multi-part replies.
-			if counterVal, ok := c.msgSeqCounters.Load(msg.ChatID); ok {
-				if counter, ok := counterVal.(*atomic.Uint64); ok {
-					seq := counter.Add(1)
-					msgToCreate.MsgSeq = uint32(seq)
-				}
-			}
-		}
-	}
+	c.applyPassiveReplyMetadata(msg.ChatID, msgToCreate)

 	// Sanitize URLs in group messages to avoid QQ's URL blacklist rejection.
 	if chatKind == "group" {
@ -305,9 +316,9 @@ func (c *QQChannel) StartTyping(ctx context.Context, chatID string) (func(), err
 }

 // SendMedia implements the channels.MediaSender interface.
-// QQ RichMediaMessage requires an HTTP/HTTPS URL — local file paths are not supported.
-// If part.Ref is already an http(s) URL it is used directly; otherwise we try
-// the media store, and skip with a warning if the resolved path is not an HTTP URL.
+// QQ group/C2C media sending is a two-step flow:
+// 1. Upload media to /files using a remote URL or base64-encoded local bytes.
+// 2. Send a msg_type=7 message using the returned file_info.
 func (c *QQChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
 	if !c.IsRunning() {
 		return channels.ErrNotRunning
@ -316,69 +327,24 @@ func (c *QQChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage)
 	chatKind := c.getChatKind(msg.ChatID)

 	for _, part := range msg.Parts {
-		// If the ref is already an HTTP(S) URL, use it directly.
-		mediaURL := part.Ref
-		if !isHTTPURL(mediaURL) {
-			// Try resolving through media store.
-			store := c.GetMediaStore()
-			if store == nil {
-				logger.WarnCF("qq", "QQ media requires HTTP/HTTPS URL, no media store available", map[string]any{
-					"ref": part.Ref,
-				})
-				continue
+		fileInfo, err := c.uploadMedia(ctx, chatKind, msg.ChatID, part)
+		if err != nil {
+			logger.ErrorCF("qq", "Failed to upload media", map[string]any{
+				"type":    part.Type,
+				"chat_id": msg.ChatID,
+				"error":   err.Error(),
+			})
+			if errors.Is(err, channels.ErrSendFailed) {
+				return err
 			}
-
-			resolved, err := store.Resolve(part.Ref)
-			if err != nil {
-				logger.ErrorCF("qq", "Failed to resolve media ref", map[string]any{
-					"ref":   part.Ref,
-					"error": err.Error(),
-				})
-				continue
-			}
-
-			if !isHTTPURL(resolved) {
-				logger.WarnCF("qq", "QQ media requires HTTP/HTTPS URL, local files not supported", map[string]any{
-					"ref":      part.Ref,
-					"resolved": resolved,
-				})
-				continue
-			}
-
-			mediaURL = resolved
+			return fmt.Errorf("qq send media: %w", channels.ErrTemporary)
 		}

-		// Map part type to QQ file type: 1=image, 2=video, 3=audio, 4=file.
-		var fileType uint64
-		switch part.Type {
-		case "image":
-			fileType = 1
-		case "video":
-			fileType = 2
-		case "audio":
-			fileType = 3
-		default:
-			fileType = 4 // file
-		}
-
-		richMedia := &dto.RichMediaMessage{
-			FileType:   fileType,
-			URL:        mediaURL,
-			SrvSendMsg: true,
-		}
-
-		var sendErr error
-		if chatKind == "group" {
-			_, sendErr = c.api.PostGroupMessage(ctx, msg.ChatID, richMedia)
-		} else {
-			_, sendErr = c.api.PostC2CMessage(ctx, msg.ChatID, richMedia)
-		}
-
-		if sendErr != nil {
+		if err := c.sendUploadedMedia(ctx, chatKind, msg.ChatID, part, fileInfo); err != nil {
 			logger.ErrorCF("qq", "Failed to send media", map[string]any{
 				"type":    part.Type,
 				"chat_id": msg.ChatID,
-				"error":   sendErr.Error(),
+				"error":   err.Error(),
 			})
 			return fmt.Errorf("qq send media: %w", channels.ErrTemporary)
 		}
@ -387,6 +353,161 @@ func (c *QQChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage)
 	return nil
 }

+type qqMediaUpload struct {
+	FileType   uint64 `json:"file_type"`
+	URL        string `json:"url,omitempty"`
+	FileData   string `json:"file_data,omitempty"`
+	SrvSendMsg bool   `json:"srv_send_msg,omitempty"`
+}
+
+func (c *QQChannel) uploadMedia(
+	ctx context.Context,
+	chatKind, chatID string,
+	part bus.MediaPart,
+) ([]byte, error) {
+	payload, err := c.buildMediaUpload(part)
+	if err != nil {
+		return nil, err
+	}
+
+	body, err := c.api.Transport(ctx, http.MethodPost, c.mediaUploadURL(chatKind, chatID), payload)
+	if err != nil {
+		return nil, err
+	}
+
+	var uploaded dto.Message
+	if err := json.Unmarshal(body, &uploaded); err != nil {
+		return nil, fmt.Errorf("qq decode media upload response: %w", err)
+	}
+	if len(uploaded.FileInfo) == 0 {
+		return nil, fmt.Errorf("qq upload media: missing file_info")
+	}
+
+	return uploaded.FileInfo, nil
+}
+
+func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) {
+	payload := &qqMediaUpload{
+		FileType: qqFileType(part.Type),
+	}
+
+	mediaRef := part.Ref
+	if isHTTPURL(mediaRef) {
+		payload.URL = mediaRef
+		return payload, nil
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	resolved, err := store.Resolve(part.Ref)
+	if err != nil {
+		return nil, fmt.Errorf("qq resolve media ref %q: %v: %w", part.Ref, err, channels.ErrSendFailed)
+	}
+
+	if isHTTPURL(resolved) {
+		payload.URL = resolved
+		return payload, nil
+	}
+
+	if limitBytes := c.maxBase64FileSizeBytes(); limitBytes > 0 {
+		info, statErr := os.Stat(resolved)
+		if statErr != nil {
+			return nil, fmt.Errorf("qq stat local media %q: %v: %w", resolved, statErr, channels.ErrSendFailed)
+		}
+		if info.Size() > limitBytes {
+			return nil, fmt.Errorf(
+				"qq local media %q exceeds max_base64_file_size_mib (%d > %d bytes): %w",
+				resolved,
+				info.Size(),
+				limitBytes,
+				channels.ErrSendFailed,
+			)
+		}
+	}
+
+	data, err := os.ReadFile(resolved)
+	if err != nil {
+		return nil, fmt.Errorf("qq read local media %q: %v: %w", resolved, err, channels.ErrSendFailed)
+	}
+
+	payload.FileData = base64.StdEncoding.EncodeToString(data)
+	return payload, nil
+}
+
+func (c *QQChannel) sendUploadedMedia(
+	ctx context.Context,
+	chatKind, chatID string,
+	part bus.MediaPart,
+	fileInfo []byte,
+) error {
+	msg := &dto.MessageToCreate{
+		Content: part.Caption,
+		MsgType: dto.RichMediaMsg,
+		Media: &dto.MediaInfo{
+			FileInfo: fileInfo,
+		},
+	}
+	c.applyPassiveReplyMetadata(chatID, msg)
+
+	if chatKind == "group" && msg.Content != "" {
+		msg.Content = sanitizeURLs(msg.Content)
+	}
+
+	if chatKind == "group" {
+		_, err := c.api.PostGroupMessage(ctx, chatID, msg)
+		return err
+	}
+	_, err := c.api.PostC2CMessage(ctx, chatID, msg)
+	return err
+}
+
+func (c *QQChannel) applyPassiveReplyMetadata(chatID string, msg *dto.MessageToCreate) {
+	if v, ok := c.lastMsgID.Load(chatID); ok {
+		if msgID, ok := v.(string); ok && msgID != "" {
+			msg.MsgID = msgID
+
+			// Increment msg_seq atomically for multi-part replies.
+			if counterVal, ok := c.msgSeqCounters.Load(chatID); ok {
+				if counter, ok := counterVal.(*atomic.Uint64); ok {
+					seq := counter.Add(1)
+					msg.MsgSeq = uint32(seq)
+				}
+			}
+		}
+	}
+}
+
+func (c *QQChannel) mediaUploadURL(chatKind, chatID string) string {
+	base := constant.APIDomain
+	if chatKind == "group" {
+		return fmt.Sprintf("%s/v2/groups/%s/files", base, chatID)
+	}
+	return fmt.Sprintf("%s/v2/users/%s/files", base, chatID)
+}
+
+func qqFileType(partType string) uint64 {
+	switch partType {
+	case "image":
+		return 1
+	case "video":
+		return 2
+	case "audio":
+		return 3
+	default:
+		return 4
+	}
+}
+
+func (c *QQChannel) maxBase64FileSizeBytes() int64 {
+	if c.config.MaxBase64FileSizeMiB <= 0 {
+		return 0
+	}
+	return c.config.MaxBase64FileSizeMiB * bytesPerMiB
+}
+
 // handleC2CMessage handles QQ private messages.
 func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 	return func(event *dto.WSPayload, data *dto.WSC2CMessageData) error {
@ -404,16 +525,30 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			return nil
 		}

-		// extract message content
-		content := data.Content
-		if content == "" {
-			logger.DebugC("qq", "Received empty message, ignoring")
+		sender := bus.SenderInfo{
+			Platform:    "qq",
+			PlatformID:  data.Author.ID,
+			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
+		}
+
+		if !c.IsAllowedSender(sender) {
+			return nil
+		}
+
+		content := strings.TrimSpace(data.Content)
+		mediaPaths, attachmentNotes := c.extractInboundAttachments(senderID, data.ID, data.Attachments)
+		for _, note := range attachmentNotes {
+			content = appendContent(content, note)
+		}
+		if content == "" && len(mediaPaths) == 0 {
+			logger.DebugC("qq", "Received empty C2C message with no attachments, ignoring")
 			return nil
 		}

 		logger.InfoCF("qq", "Received C2C message", map[string]any{
-			"sender": senderID,
-			"length": len(content),
+			"sender":      senderID,
+			"length":      len(content),
+			"media_count": len(mediaPaths),
 		})

 		// Store chat routing context.
@ -427,23 +562,13 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			"account_id": senderID,
 		}

-		sender := bus.SenderInfo{
-			Platform:    "qq",
-			PlatformID:  data.Author.ID,
-			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
-		}
-
-		if !c.IsAllowedSender(sender) {
-			return nil
-		}
-
 		c.HandleMessage(c.ctx,
 			bus.Peer{Kind: "direct", ID: senderID},
 			data.ID,
 			senderID,
 			senderID,
 			content,
-			[]string{},
+			mediaPaths,
 			metadata,
 			sender,
 		)
@ -469,24 +594,38 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			return nil
 		}

-		// extract message content (remove @ bot part)
-		content := data.Content
-		if content == "" {
-			logger.DebugC("qq", "Received empty group message, ignoring")
+		sender := bus.SenderInfo{
+			Platform:    "qq",
+			PlatformID:  data.Author.ID,
+			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
+		}
+
+		if !c.IsAllowedSender(sender) {
 			return nil
 		}

-		// GroupAT event means bot is always mentioned; apply group trigger filtering
+		content := strings.TrimSpace(data.Content)
+		mediaPaths, attachmentNotes := c.extractInboundAttachments(data.GroupID, data.ID, data.Attachments)
+		for _, note := range attachmentNotes {
+			content = appendContent(content, note)
+		}
+
+		// GroupAT event means bot is always mentioned; apply group trigger filtering.
 		respond, cleaned := c.ShouldRespondInGroup(true, content)
 		if !respond {
 			return nil
 		}
 		content = cleaned
+		if content == "" && len(mediaPaths) == 0 {
+			logger.DebugC("qq", "Received empty group message with no attachments, ignoring")
+			return nil
+		}

 		logger.InfoCF("qq", "Received group AT message", map[string]any{
-			"sender": senderID,
-			"group":  data.GroupID,
-			"length": len(content),
+			"sender":      senderID,
+			"group":       data.GroupID,
+			"length":      len(content),
+			"media_count": len(mediaPaths),
 		})

 		// Store chat routing context using GroupID as chatID.
@ -501,23 +640,13 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			"group_id":   data.GroupID,
 		}

-		sender := bus.SenderInfo{
-			Platform:    "qq",
-			PlatformID:  data.Author.ID,
-			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
-		}
-
-		if !c.IsAllowedSender(sender) {
-			return nil
-		}
-
 		c.HandleMessage(c.ctx,
 			bus.Peer{Kind: "group", ID: data.GroupID},
 			data.ID,
 			senderID,
 			data.GroupID,
 			content,
-			[]string{},
+			mediaPaths,
 			metadata,
 			sender,
 		)
@ -526,6 +655,157 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 	}
 }

+func (c *QQChannel) extractInboundAttachments(
+	chatID, messageID string,
+	attachments []*dto.MessageAttachment,
+) ([]string, []string) {
+	if len(attachments) == 0 {
+		return nil, nil
+	}
+
+	scope := channels.BuildMediaScope("qq", chatID, messageID)
+	mediaPaths := make([]string, 0, len(attachments))
+	notes := make([]string, 0, len(attachments))
+
+	storeMedia := func(localPath string, attachment *dto.MessageAttachment) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename:    qqAttachmentFilename(attachment),
+				ContentType: attachment.ContentType,
+				Source:      "qq",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath
+	}
+
+	for _, attachment := range attachments {
+		if attachment == nil {
+			continue
+		}
+
+		filename := qqAttachmentFilename(attachment)
+		if localPath := c.downloadAttachment(attachment.URL, filename); localPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(localPath, attachment))
+		} else if attachment.URL != "" {
+			mediaPaths = append(mediaPaths, attachment.URL)
+		}
+
+		notes = append(notes, qqAttachmentNote(attachment))
+	}
+
+	return mediaPaths, notes
+}
+
+func (c *QQChannel) downloadAttachment(urlStr, filename string) string {
+	if urlStr == "" {
+		return ""
+	}
+	if c.downloadFn != nil {
+		return c.downloadFn(urlStr, filename)
+	}
+
+	return utils.DownloadFile(urlStr, filename, utils.DownloadOptions{
+		LoggerPrefix: "qq",
+		ExtraHeaders: c.downloadHeaders(),
+	})
+}
+
+func (c *QQChannel) downloadHeaders() map[string]string {
+	headers := map[string]string{}
+
+	if c.config.AppID != "" {
+		headers["X-Union-Appid"] = c.config.AppID
+	}
+
+	if c.tokenSource != nil {
+		if tk, err := c.tokenSource.Token(); err == nil && tk.AccessToken != "" {
+			auth := strings.TrimSpace(tk.TokenType + " " + tk.AccessToken)
+			if auth != "" {
+				headers["Authorization"] = auth
+			}
+		}
+	}
+
+	if len(headers) == 0 {
+		return nil
+	}
+	return headers
+}
+
+func qqAttachmentFilename(attachment *dto.MessageAttachment) string {
+	if attachment == nil {
+		return "attachment"
+	}
+	if attachment.FileName != "" {
+		return attachment.FileName
+	}
+	if attachment.URL != "" {
+		if parsed, err := url.Parse(attachment.URL); err == nil {
+			if base := path.Base(parsed.Path); base != "" && base != "." && base != "/" {
+				return base
+			}
+		}
+	}
+
+	switch qqAttachmentKind(attachment) {
+	case "image":
+		return "image"
+	case "audio":
+		return "audio"
+	case "video":
+		return "video"
+	default:
+		return "attachment"
+	}
+}
+
+func qqAttachmentKind(attachment *dto.MessageAttachment) string {
+	if attachment == nil {
+		return "file"
+	}
+
+	contentType := strings.ToLower(attachment.ContentType)
+	filename := strings.ToLower(attachment.FileName)
+
+	switch {
+	case strings.HasPrefix(contentType, "image/"):
+		return "image"
+	case strings.HasPrefix(contentType, "video/"):
+		return "video"
+	case strings.HasPrefix(contentType, "audio/"), contentType == "application/ogg", contentType == "application/x-ogg":
+		return "audio"
+	}
+
+	switch filepath.Ext(filename) {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus", ".silk":
+		return "audio"
+	default:
+		return "file"
+	}
+}
+
+func qqAttachmentNote(attachment *dto.MessageAttachment) string {
+	filename := qqAttachmentFilename(attachment)
+
+	switch qqAttachmentKind(attachment) {
+	case "image":
+		return fmt.Sprintf("[image: %s]", filename)
+	case "audio":
+		return fmt.Sprintf("[audio: %s]", filename)
+	case "video":
+		return fmt.Sprintf("[video: %s]", filename)
+	default:
+		return fmt.Sprintf("[file: %s]", filename)
+	}
+}
+
 // isDuplicate checks whether a message has been seen within the TTL window.
 // It also enforces a hard cap on map size by evicting oldest entries.
 func (c *QQChannel) isDuplicate(messageID string) bool {
@ -587,6 +867,16 @@ func isHTTPURL(s string) bool {
 	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
 }

+func appendContent(content, suffix string) string {
+	if suffix == "" {
+		return content
+	}
+	if content == "" {
+		return suffix
+	}
+	return content + "\n" + suffix
+}
+
 // urlPattern matches URLs with explicit http(s):// scheme.
 // Only scheme-prefixed URLs are matched to avoid false positives on bare text
 // like version numbers (e.g., "1.2.3") or domain-like fragments.
--- a/pkg/channels/qq/qq_test.go
+++ b/pkg/channels/qq/qq_test.go
@ -2,13 +2,22 @@ package qq

 import (
 	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"os"
+	"strings"
+	"sync/atomic"
 	"testing"
 	"time"

 	"github.com/tencent-connect/botgo/dto"
+	"github.com/tencent-connect/botgo/openapi/options"

 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
 )

 func TestHandleC2CMessage_IncludesAccountIDMetadata(t *testing.T) {
@ -50,3 +59,438 @@ func TestHandleC2CMessage_IncludesAccountIDMetadata(t *testing.T) {
 		}
 	}
 }
+
+func TestHandleC2CMessage_AttachmentOnlyPublishesMedia(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+	localPath := writeTempFile(t, t.TempDir(), "image.png", []byte("fake-image"))
+
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+		downloadFn: func(urlStr, filename string) string {
+			if filename != "image.png" {
+				t.Fatalf("download filename = %q, want image.png", filename)
+			}
+			return localPath
+		},
+	}
+	ch.SetMediaStore(store)
+
+	err := ch.handleC2CMessage()(nil, &dto.WSC2CMessageData{
+		ID:      "msg-attachment",
+		Content: "",
+		Author: &dto.User{
+			ID: "7750283E123456",
+		},
+		Attachments: []*dto.MessageAttachment{{
+			URL:         "https://example.com/image.png",
+			FileName:    "image.png",
+			ContentType: "image/png",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("handleC2CMessage() error = %v", err)
+	}
+
+	inbound := waitInboundMessage(t, messageBus)
+	if inbound.Content != "[image: image.png]" {
+		t.Fatalf("inbound.Content = %q", inbound.Content)
+	}
+	if len(inbound.Media) != 1 {
+		t.Fatalf("len(inbound.Media) = %d, want 1", len(inbound.Media))
+	}
+	if !strings.HasPrefix(inbound.Media[0], "media://") {
+		t.Fatalf("inbound.Media[0] = %q, want media:// ref", inbound.Media[0])
+	}
+	_, meta, err := store.ResolveWithMeta(inbound.Media[0])
+	if err != nil {
+		t.Fatalf("ResolveWithMeta() error = %v", err)
+	}
+	if meta.Filename != "image.png" {
+		t.Fatalf("meta.Filename = %q, want image.png", meta.Filename)
+	}
+	if meta.ContentType != "image/png" {
+		t.Fatalf("meta.ContentType = %q, want image/png", meta.ContentType)
+	}
+}
+
+func TestHandleGroupATMessage_AttachmentOnlyPublishesMedia(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+	localPath := writeTempFile(t, t.TempDir(), "report.pdf", []byte("fake-pdf"))
+
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+		downloadFn: func(urlStr, filename string) string {
+			if filename != "report.pdf" {
+				t.Fatalf("download filename = %q, want report.pdf", filename)
+			}
+			return localPath
+		},
+	}
+	ch.SetMediaStore(store)
+
+	err := ch.handleGroupATMessage()(nil, &dto.WSGroupATMessageData{
+		ID:      "group-attachment",
+		GroupID: "group-1",
+		Content: "",
+		Author: &dto.User{
+			ID: "7750283E123456",
+		},
+		Attachments: []*dto.MessageAttachment{{
+			URL:         "https://example.com/report.pdf",
+			FileName:    "report.pdf",
+			ContentType: "application/pdf",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("handleGroupATMessage() error = %v", err)
+	}
+
+	inbound := waitInboundMessage(t, messageBus)
+	if inbound.Content != "[file: report.pdf]" {
+		t.Fatalf("inbound.Content = %q", inbound.Content)
+	}
+	if len(inbound.Media) != 1 {
+		t.Fatalf("len(inbound.Media) = %d, want 1", len(inbound.Media))
+	}
+	if !strings.HasPrefix(inbound.Media[0], "media://") {
+		t.Fatalf("inbound.Media[0] = %q, want media:// ref", inbound.Media[0])
+	}
+	if inbound.Peer.Kind != "group" || inbound.Peer.ID != "group-1" {
+		t.Fatalf("inbound.Peer = %+v, want group/group-1", inbound.Peer)
+	}
+}
+
+func TestSendMedia_UploadsLocalFileAsBase64(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	tmpFile, err := os.CreateTemp(t.TempDir(), "qq-media-*.png")
+	if err != nil {
+		t.Fatalf("CreateTemp() error = %v", err)
+	}
+	defer tmpFile.Close()
+
+	content := []byte("local-image-data")
+	if _, writeErr := tmpFile.Write(content); writeErr != nil {
+		t.Fatalf("Write() error = %v", writeErr)
+	}
+
+	ref, err := store.Store(tmpFile.Name(), media.MediaMeta{
+		Filename:    "reply.png",
+		ContentType: "image/png",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("uploaded-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+	ch.lastMsgID.Store("group-1", "msg-1")
+	ch.msgSeqCounters.Store("group-1", new(atomic.Uint64))
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type:    "image",
+			Ref:     ref,
+			Caption: "see https://example.com/image",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	upload := api.transportCalls[0]
+	if upload.method != "POST" {
+		t.Fatalf("upload method = %q, want POST", upload.method)
+	}
+	if upload.url != "https://api.sgroup.qq.com/v2/groups/group-1/files" {
+		t.Fatalf("upload url = %q", upload.url)
+	}
+	if upload.body.URL != "" {
+		t.Fatalf("upload URL = %q, want empty", upload.body.URL)
+	}
+	wantBase64 := base64.StdEncoding.EncodeToString(content)
+	if upload.body.FileData != wantBase64 {
+		t.Fatalf("upload file_data = %q, want %q", upload.body.FileData, wantBase64)
+	}
+	if upload.body.FileType != 1 {
+		t.Fatalf("upload file_type = %d, want 1", upload.body.FileType)
+	}
+
+	if len(api.groupMessages) != 1 {
+		t.Fatalf("groupMessages = %d, want 1", len(api.groupMessages))
+	}
+	msg, ok := api.groupMessages[0].(*dto.MessageToCreate)
+	if !ok {
+		t.Fatalf("groupMessages[0] type = %T, want *dto.MessageToCreate", api.groupMessages[0])
+	}
+	if msg.MsgType != dto.RichMediaMsg {
+		t.Fatalf("msg.MsgType = %d, want %d", msg.MsgType, dto.RichMediaMsg)
+	}
+	if msg.MsgID != "msg-1" {
+		t.Fatalf("msg.MsgID = %q, want msg-1", msg.MsgID)
+	}
+	if msg.MsgSeq != 1 {
+		t.Fatalf("msg.MsgSeq = %d, want 1", msg.MsgSeq)
+	}
+	if msg.Content != "see https://example。com/image" {
+		t.Fatalf("msg.Content = %q", msg.Content)
+	}
+	if msg.Media == nil || string(msg.Media.FileInfo) != "uploaded-file-info" {
+		t.Fatalf("msg.Media.FileInfo = %q, want uploaded-file-info", string(msg.Media.FileInfo))
+	}
+}
+
+func TestSendMedia_UsesRemoteURLUploadForC2C(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("remote-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.chatType.Store("user-1", "direct")
+
+	err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "user-1",
+		Parts: []bus.MediaPart{{
+			Type: "file",
+			Ref:  "https://cdn.example.com/report.pdf",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	upload := api.transportCalls[0]
+	if upload.url != "https://api.sgroup.qq.com/v2/users/user-1/files" {
+		t.Fatalf("upload url = %q", upload.url)
+	}
+	if upload.body.URL != "https://cdn.example.com/report.pdf" {
+		t.Fatalf("upload URL = %q", upload.body.URL)
+	}
+	if upload.body.FileData != "" {
+		t.Fatalf("upload file_data = %q, want empty", upload.body.FileData)
+	}
+	if upload.body.FileType != 4 {
+		t.Fatalf("upload file_type = %d, want 4", upload.body.FileType)
+	}
+
+	if len(api.c2cMessages) != 1 {
+		t.Fatalf("c2cMessages = %d, want 1", len(api.c2cMessages))
+	}
+	msg, ok := api.c2cMessages[0].(*dto.MessageToCreate)
+	if !ok {
+		t.Fatalf("c2cMessages[0] type = %T, want *dto.MessageToCreate", api.c2cMessages[0])
+	}
+	if msg.MsgType != dto.RichMediaMsg {
+		t.Fatalf("msg.MsgType = %d, want %d", msg.MsgType, dto.RichMediaMsg)
+	}
+	if msg.Media == nil || string(msg.Media.FileInfo) != "remote-file-info" {
+		t.Fatalf("msg.Media.FileInfo = %q, want remote-file-info", string(msg.Media.FileInfo))
+	}
+}
+
+func TestSendMedia_ReturnsSendFailedWithoutMediaStore(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         &fakeQQAPI{},
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.chatType.Store("group-1", "group")
+
+	err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "image",
+			Ref:  "media://missing",
+		}},
+	})
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("SendMedia() error = %v, want ErrSendFailed", err)
+	}
+}
+
+func TestSendMedia_ReturnsSendFailedWhenLocalFileExceedsBase64MiBLimit(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	tmpFile, err := os.CreateTemp(t.TempDir(), "qq-media-too-large-*.bin")
+	if err != nil {
+		t.Fatalf("CreateTemp() error = %v", err)
+	}
+	defer tmpFile.Close()
+
+	content := make([]byte, bytesPerMiB+1)
+	if _, writeErr := tmpFile.Write(content); writeErr != nil {
+		t.Fatalf("Write() error = %v", writeErr)
+	}
+
+	ref, err := store.Store(tmpFile.Name(), media.MediaMeta{
+		Filename:    "large.bin",
+		ContentType: "application/octet-stream",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		config: config.QQConfig{
+			MaxBase64FileSizeMiB: 1,
+		},
+		api:   api,
+		dedup: make(map[string]time.Time),
+		done:  make(chan struct{}),
+		ctx:   context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "file",
+			Ref:  ref,
+		}},
+	})
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("SendMedia() error = %v, want ErrSendFailed", err)
+	}
+	if len(api.transportCalls) != 0 {
+		t.Fatalf("transportCalls = %d, want 0", len(api.transportCalls))
+	}
+}
+
+type fakeQQAPI struct {
+	transportResp  []byte
+	transportErr   error
+	groupErr       error
+	c2cErr         error
+	transportCalls []fakeTransportCall
+	groupMessages  []dto.APIMessage
+	c2cMessages    []dto.APIMessage
+}
+
+type fakeTransportCall struct {
+	method string
+	url    string
+	body   qqMediaUpload
+}
+
+func (f *fakeQQAPI) WS(
+	context.Context,
+	map[string]string,
+	string,
+) (*dto.WebsocketAP, error) {
+	return nil, nil
+}
+
+func (f *fakeQQAPI) PostGroupMessage(
+	_ context.Context,
+	_ string,
+	msg dto.APIMessage,
+	_ ...options.Option,
+) (*dto.Message, error) {
+	f.groupMessages = append(f.groupMessages, msg)
+	return &dto.Message{}, f.groupErr
+}
+
+func (f *fakeQQAPI) PostC2CMessage(
+	_ context.Context,
+	_ string,
+	msg dto.APIMessage,
+	_ ...options.Option,
+) (*dto.Message, error) {
+	f.c2cMessages = append(f.c2cMessages, msg)
+	return &dto.Message{}, f.c2cErr
+}
+
+func (f *fakeQQAPI) Transport(_ context.Context, method, url string, body any) ([]byte, error) {
+	upload, ok := body.(*qqMediaUpload)
+	if !ok {
+		return nil, errors.New("unexpected transport body type")
+	}
+	f.transportCalls = append(f.transportCalls, fakeTransportCall{
+		method: method,
+		url:    url,
+		body:   *upload,
+	})
+	return f.transportResp, f.transportErr
+}
+
+func mustJSON(t *testing.T, v any) []byte {
+	t.Helper()
+
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	return b
+}
+
+func waitInboundMessage(t *testing.T, messageBus *bus.MessageBus) bus.InboundMessage {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	for {
+		select {
+		case <-ctx.Done():
+			t.Fatal("timeout waiting for inbound message")
+		case inbound, ok := <-messageBus.InboundChan():
+			if !ok {
+				t.Fatal("expected inbound message")
+			}
+			return inbound
+		}
+	}
+}
+
+func writeTempFile(t *testing.T, dir, name string, content []byte) string {
+	t.Helper()
+
+	path := dir + "/" + name
+	if err := os.WriteFile(path, content, 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	return path
+}
--- a/pkg/commands/builtin.go
+++ b/pkg/commands/builtin.go
@ -13,5 +13,6 @@ func BuiltinDefinitions() []Definition {
 		switchCommand(),
 		checkCommand(),
 		clearCommand(),
+		reloadCommand(),
 	}
 }
--- a/pkg/commands/cmd_reload.go
+++ b/pkg/commands/cmd_reload.go
@ -0,0 +1,20 @@
+package commands
+
+import "context"
+
+func reloadCommand() Definition {
+	return Definition{
+		Name:        "reload",
+		Description: "Reload the configuration file",
+		Usage:       "/reload",
+		Handler: func(_ context.Context, req Request, rt *Runtime) error {
+			if rt == nil || rt.ReloadConfig == nil {
+				return req.Reply(unavailableMsg)
+			}
+			if err := rt.ReloadConfig(); err != nil {
+				return req.Reply("Failed to reload configuration: " + err.Error())
+			}
+			return req.Reply("Config reload triggered!")
+		},
+	}
+}
--- a/pkg/commands/runtime.go
+++ b/pkg/commands/runtime.go
@ -14,4 +14,5 @@ type Runtime struct {
 	SwitchModel        func(value string) (oldModel string, err error)
 	SwitchChannel      func(value string) error
 	ClearHistory       func() error
+	ReloadConfig       func() error
 }
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@ -241,8 +241,17 @@ type AgentDefaults struct {
 	MaxMediaSize              int            `json:"max_media_size,omitempty"        env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"`
 	TaskReminderInterval      int            `json:"task_reminder_interval"          env:"PICOCLAW_AGENTS_DEFAULTS_TASK_REMINDER_INTERVAL"`
 	Orchestration             bool           `json:"orchestration,omitempty"         env:"PICOCLAW_AGENTS_DEFAULTS_ORCHESTRATION"`
-	Routing                   *RoutingConfig `json:"routing,omitempty"`
-	OCR                       *OCRConfig     `json:"ocr,omitempty"`
+	Routing                   *RoutingConfig     `json:"routing,omitempty"`
+	OCR                       *OCRConfig         `json:"ocr,omitempty"`
+	ToolFeedback              ToolFeedbackConfig `json:"tool_feedback,omitempty"`
+}
+
+// ToolFeedbackConfig controls whether tool execution details are sent to the
+// chat channel as real-time feedback messages. When enabled, every tool call
+// produces a short notification with the tool name and its parameters.
+type ToolFeedbackConfig struct {
+	Enabled       bool `json:"enabled"         env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED"`
+	MaxArgsLength int  `json:"max_args_length" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH"`
 }

 // OCRConfig configures the external OCR command for PDF text extraction.
@ -262,7 +271,10 @@ func (c *OCRConfig) GetOCRTimeout() int {
 	return 600
 }

-const DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+const (
+	DefaultMaxMediaSize                = 20 * 1024 * 1024 // 20 MB
+	DefaultWeComAIBotProcessingMessage = "⏳ Processing, please wait. The results will be sent shortly."
+)

 func (d *AgentDefaults) GetMaxMediaSize() int {
 	if d.MaxMediaSize > 0 {
@ -271,6 +283,19 @@ func (d *AgentDefaults) GetMaxMediaSize() int {
 	return DefaultMaxMediaSize
 }

+// GetToolFeedbackMaxArgsLength returns the max args preview length for tool feedback messages.
+func (d *AgentDefaults) GetToolFeedbackMaxArgsLength() int {
+	if d.ToolFeedback.MaxArgsLength > 0 {
+		return d.ToolFeedback.MaxArgsLength
+	}
+	return 300
+}
+
+// IsToolFeedbackEnabled returns true when tool feedback messages should be sent to the chat.
+func (d *AgentDefaults) IsToolFeedbackEnabled() bool {
+	return d.ToolFeedback.Enabled
+}
+
 // GetModelName returns the effective model name for the agent defaults.
 // It prefers the new "model_name" field but falls back to "model" for backward compatibility.
 func (d *AgentDefaults) GetModelName() string {
@ -381,9 +406,10 @@ type QQConfig struct {
 	AppSecret          string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
 	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	MaxMessageLength   int                 `json:"max_message_length"      env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
-	SendMarkdown       bool                `json:"send_markdown"           env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+	MaxMessageLength     int                 `json:"max_message_length"       env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
+	MaxBase64FileSizeMiB int64               `json:"max_base64_file_size_mib" env:"PICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIB"`
+	SendMarkdown         bool                `json:"send_markdown"            env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
+	ReasoningChannelID   string              `json:"reasoning_channel_id"     env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
 }

 type DingTalkConfig struct {
@ -485,8 +511,9 @@ type WeComAIBotConfig struct {
 	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_WECOM_AIBOT_ALLOW_FROM"`
 	ReplyTimeout       int                 `json:"reply_timeout"        env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REPLY_TIMEOUT"`
 	MaxSteps           int                 `json:"max_steps"            env:"PICOCLAW_CHANNELS_WECOM_AIBOT_MAX_STEPS"`       // Maximum streaming steps
-	WelcomeMessage     string              `json:"welcome_message"      env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"` // Sent on enter_chat event; empty = no welcome
-	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
+	WelcomeMessage     string              `json:"welcome_message"              env:"PICOCLAW_CHANNELS_WECOM_AIBOT_WELCOME_MESSAGE"` // Sent on enter_chat event; empty = no welcome
+	ProcessingMessage  string              `json:"processing_message,omitempty" env:"PICOCLAW_CHANNELS_WECOM_AIBOT_PROCESSING_MESSAGE"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"         env:"PICOCLAW_CHANNELS_WECOM_AIBOT_REASONING_CHANNEL_ID"`
 }

 type PicoConfig struct {
@ -849,6 +876,8 @@ type MCPServerConfig struct {
 	Headers map[string]string `json:"headers,omitempty"`
 	// Timeout is the maximum duration in seconds for tool calls to this server (default: 60)
 	Timeout int `json:"timeout,omitempty"`
+	// Deferred controls whether this server's tools are registered as hidden (deferred/discovery mode).
+	Deferred *bool `json:"deferred,omitempty"`
 }

 // MCPConfig defines configuration for all MCP servers
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@ -35,6 +35,10 @@ func DefaultConfig() *Config {
 				MaxToolIterations:         50,
 				SummarizeMessageThreshold: 20,
 				SummarizeTokenPercent:     75,
+				ToolFeedback: ToolFeedbackConfig{
+					Enabled:       true,
+					MaxArgsLength: 300,
+				},
 			},
 		},
 		Bindings: []AgentBinding{},
@ -81,11 +85,12 @@ func DefaultConfig() *Config {
 				AllowFrom: FlexibleStringSlice{},
 			},
 			QQ: QQConfig{
-				Enabled:          false,
-				AppID:            "",
-				AppSecret:        "",
-				AllowFrom:        FlexibleStringSlice{},
-				MaxMessageLength: 2000,
+				Enabled:              false,
+				AppID:                "",
+				AppSecret:            "",
+				AllowFrom:            FlexibleStringSlice{},
+				MaxMessageLength:     2000,
+				MaxBase64FileSizeMiB: 0,
 			},
 			DingTalk: DingTalkConfig{
 				Enabled:      false,
@ -158,14 +163,15 @@ func DefaultConfig() *Config {
 				ReplyTimeout:   5,
 			},
 			WeComAIBot: WeComAIBotConfig{
-				Enabled:        false,
-				Token:          "",
-				EncodingAESKey: "",
-				WebhookPath:    "/webhook/wecom-aibot",
-				AllowFrom:      FlexibleStringSlice{},
-				ReplyTimeout:   5,
-				MaxSteps:       10,
-				WelcomeMessage: "Hello! I'm your AI assistant. How can I help you today?",
+				Enabled:           false,
+				Token:             "",
+				EncodingAESKey:    "",
+				WebhookPath:       "/webhook/wecom-aibot",
+				AllowFrom:         FlexibleStringSlice{},
+				ReplyTimeout:      5,
+				MaxSteps:          10,
+				WelcomeMessage:    "Hello! I'm your AI assistant. How can I help you today?",
+				ProcessingMessage: DefaultWeComAIBotProcessingMessage,
 			},
 			Pico: PicoConfig{
 				Enabled:        false,
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@ -468,3 +468,84 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {

 	return result
 }
+
+// protocolProviderMapping maps a model protocol prefix (the part before "/" in
+// the Model field) to a function that extracts the corresponding ProviderConfig
+// from the legacy ProvidersConfig.  Used by InheritProviderCredentials.
+var protocolProviderMapping = map[string]func(p ProvidersConfig) ProviderConfig{
+	"openai":         func(p ProvidersConfig) ProviderConfig { return p.OpenAI.ProviderConfig },
+	"anthropic":      func(p ProvidersConfig) ProviderConfig { return p.Anthropic },
+	"litellm":        func(p ProvidersConfig) ProviderConfig { return p.LiteLLM },
+	"openrouter":     func(p ProvidersConfig) ProviderConfig { return p.OpenRouter },
+	"groq":           func(p ProvidersConfig) ProviderConfig { return p.Groq },
+	"zhipu":          func(p ProvidersConfig) ProviderConfig { return p.Zhipu },
+	"vllm":           func(p ProvidersConfig) ProviderConfig { return p.VLLM },
+	"gemini":         func(p ProvidersConfig) ProviderConfig { return p.Gemini },
+	"nvidia":         func(p ProvidersConfig) ProviderConfig { return p.Nvidia },
+	"ollama":         func(p ProvidersConfig) ProviderConfig { return p.Ollama },
+	"moonshot":       func(p ProvidersConfig) ProviderConfig { return p.Moonshot },
+	"shengsuanyun":   func(p ProvidersConfig) ProviderConfig { return p.ShengSuanYun },
+	"deepseek":       func(p ProvidersConfig) ProviderConfig { return p.DeepSeek },
+	"cerebras":       func(p ProvidersConfig) ProviderConfig { return p.Cerebras },
+	"vivgrid":        func(p ProvidersConfig) ProviderConfig { return p.Vivgrid },
+	"volcengine":     func(p ProvidersConfig) ProviderConfig { return p.VolcEngine },
+	"github-copilot": func(p ProvidersConfig) ProviderConfig { return p.GitHubCopilot },
+	"antigravity":    func(p ProvidersConfig) ProviderConfig { return p.Antigravity },
+	"qwen":           func(p ProvidersConfig) ProviderConfig { return p.Qwen },
+	"mistral":        func(p ProvidersConfig) ProviderConfig { return p.Mistral },
+	"avian":          func(p ProvidersConfig) ProviderConfig { return p.Avian },
+	"minimax":        func(p ProvidersConfig) ProviderConfig { return p.Minimax },
+	"longcat":        func(p ProvidersConfig) ProviderConfig { return p.LongCat },
+	"modelscope":     func(p ProvidersConfig) ProviderConfig { return p.ModelScope },
+	"novita":         func(p ProvidersConfig) ProviderConfig { return p.Novita },
+}
+
+// InheritProviderCredentials fills in missing api_key, api_base, proxy, and
+// request_timeout on model_list entries from the matching legacy providers
+// configuration.  The match is determined by the protocol prefix in the Model
+// field (e.g. "deepseek/deepseek-chat" matches providers.deepseek).
+//
+// Only empty fields are filled — any value explicitly set on a model_list entry
+// takes precedence.  This function modifies the slice in place.
+//
+// This bridges the gap described in issue #1635: users who configure
+// credentials once in the providers section expect model_list entries using
+// the same protocol to "just work" without duplicating credentials.
+func InheritProviderCredentials(models []ModelConfig, providers ProvidersConfig) {
+	if providers.IsEmpty() {
+		return
+	}
+
+	for i := range models {
+		m := &models[i]
+
+		// Extract protocol prefix from Model field
+		protocol := ""
+		if idx := strings.Index(m.Model, "/"); idx > 0 {
+			protocol = strings.ToLower(m.Model[:idx])
+		}
+		if protocol == "" {
+			continue
+		}
+
+		getProvider, ok := protocolProviderMapping[protocol]
+		if !ok {
+			continue
+		}
+		pc := getProvider(providers)
+
+		// Only fill empty fields — explicit model_list values win
+		if m.APIKey == "" && pc.APIKey != "" {
+			m.APIKey = pc.APIKey
+		}
+		if m.APIBase == "" && pc.APIBase != "" {
+			m.APIBase = pc.APIBase
+		}
+		if m.Proxy == "" && pc.Proxy != "" {
+			m.Proxy = pc.Proxy
+		}
+		if m.RequestTimeout == 0 && pc.RequestTimeout != 0 {
+			m.RequestTimeout = pc.RequestTimeout
+		}
+	}
+}
--- a/pkg/config/migration_test.go
+++ b/pkg/config/migration_test.go
@ -613,3 +613,143 @@ func TestConvertProvidersToModelList_LegacyModelWithProtocolPrefix(t *testing.T)
 		t.Errorf("Model = %q, want %q (should not duplicate prefix)", result[0].Model, "openrouter/auto")
 	}
 }
+
+// ---------- InheritProviderCredentials tests ----------
+
+func TestInheritProviderCredentials_FillsMissingAPIKey(t *testing.T) {
+	models := []ModelConfig{
+		{ModelName: "my-deepseek", Model: "deepseek/deepseek-chat"},
+	}
+	providers := ProvidersConfig{
+		DeepSeek: ProviderConfig{
+			APIKey:  "sk-deepseek-from-providers",
+			APIBase: "https://api.deepseek.com/v1",
+		},
+	}
+
+	InheritProviderCredentials(models, providers)
+
+	if models[0].APIKey != "sk-deepseek-from-providers" {
+		t.Errorf("APIKey = %q, want %q", models[0].APIKey, "sk-deepseek-from-providers")
+	}
+	if models[0].APIBase != "https://api.deepseek.com/v1" {
+		t.Errorf("APIBase = %q, want %q", models[0].APIBase, "https://api.deepseek.com/v1")
+	}
+}
+
+func TestInheritProviderCredentials_ExplicitValuesTakePrecedence(t *testing.T) {
+	models := []ModelConfig{
+		{
+			ModelName: "my-openai",
+			Model:     "openai/gpt-5.4",
+			APIKey:    "sk-explicit-model-key",
+			APIBase:   "https://my-custom-endpoint.com/v1",
+		},
+	}
+	providers := ProvidersConfig{
+		OpenAI: OpenAIProviderConfig{
+			ProviderConfig: ProviderConfig{
+				APIKey:  "sk-provider-key",
+				APIBase: "https://api.openai.com/v1",
+			},
+		},
+	}
+
+	InheritProviderCredentials(models, providers)
+
+	if models[0].APIKey != "sk-explicit-model-key" {
+		t.Errorf("APIKey = %q, want %q (explicit should win)", models[0].APIKey, "sk-explicit-model-key")
+	}
+	if models[0].APIBase != "https://my-custom-endpoint.com/v1" {
+		t.Errorf("APIBase = %q, want %q (explicit should win)", models[0].APIBase, "https://my-custom-endpoint.com/v1")
+	}
+}
+
+func TestInheritProviderCredentials_MultipleModels(t *testing.T) {
+	models := []ModelConfig{
+		{ModelName: "groq-llama", Model: "groq/llama-3.1-70b"},
+		{ModelName: "zhipu-glm", Model: "zhipu/glm-4"},
+		{ModelName: "custom-openai", Model: "openai/gpt-5.4", APIKey: "sk-already-set"},
+	}
+	providers := ProvidersConfig{
+		Groq:  ProviderConfig{APIKey: "gsk-groq-key", Proxy: "http://proxy:8080"},
+		Zhipu: ProviderConfig{APIKey: "zhipu-key-123", APIBase: "https://zhipu.example.com"},
+		OpenAI: OpenAIProviderConfig{
+			ProviderConfig: ProviderConfig{APIKey: "sk-should-not-override"},
+		},
+	}
+
+	InheritProviderCredentials(models, providers)
+
+	// groq model should inherit
+	if models[0].APIKey != "gsk-groq-key" {
+		t.Errorf("groq APIKey = %q, want %q", models[0].APIKey, "gsk-groq-key")
+	}
+	if models[0].Proxy != "http://proxy:8080" {
+		t.Errorf("groq Proxy = %q, want %q", models[0].Proxy, "http://proxy:8080")
+	}
+
+	// zhipu model should inherit
+	if models[1].APIKey != "zhipu-key-123" {
+		t.Errorf("zhipu APIKey = %q, want %q", models[1].APIKey, "zhipu-key-123")
+	}
+	if models[1].APIBase != "https://zhipu.example.com" {
+		t.Errorf("zhipu APIBase = %q, want %q", models[1].APIBase, "https://zhipu.example.com")
+	}
+
+	// openai model already has key — should NOT be overridden
+	if models[2].APIKey != "sk-already-set" {
+		t.Errorf("openai APIKey = %q, want %q (should not be overridden)", models[2].APIKey, "sk-already-set")
+	}
+}
+
+func TestInheritProviderCredentials_NoMatchingProvider(t *testing.T) {
+	models := []ModelConfig{
+		{ModelName: "my-model", Model: "novelai/some-model"},
+	}
+	providers := ProvidersConfig{
+		DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+	}
+
+	InheritProviderCredentials(models, providers)
+
+	// No matching provider for "novelai" protocol — should stay empty
+	if models[0].APIKey != "" {
+		t.Errorf("APIKey = %q, want empty (no matching provider)", models[0].APIKey)
+	}
+}
+
+func TestInheritProviderCredentials_EmptyProviders(t *testing.T) {
+	models := []ModelConfig{
+		{ModelName: "my-model", Model: "openai/gpt-5.4"},
+	}
+	providers := ProvidersConfig{} // all empty
+
+	InheritProviderCredentials(models, providers)
+
+	// Empty providers — nothing to inherit
+	if models[0].APIKey != "" {
+		t.Errorf("APIKey = %q, want empty", models[0].APIKey)
+	}
+}
+
+func TestInheritProviderCredentials_InheritsRequestTimeout(t *testing.T) {
+	models := []ModelConfig{
+		{ModelName: "my-ollama", Model: "ollama/llama3.2:3b"},
+	}
+	providers := ProvidersConfig{
+		Ollama: ProviderConfig{
+			APIBase:        "http://localhost:11434",
+			RequestTimeout: 120,
+		},
+	}
+
+	InheritProviderCredentials(models, providers)
+
+	if models[0].APIBase != "http://localhost:11434" {
+		t.Errorf("APIBase = %q, want %q", models[0].APIBase, "http://localhost:11434")
+	}
+	if models[0].RequestTimeout != 120 {
+		t.Errorf("RequestTimeout = %d, want 120", models[0].RequestTimeout)
+	}
+}
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@ -12,11 +12,12 @@ import (
 )

 type Server struct {
-	server    *http.Server
-	mu        sync.RWMutex
-	ready     bool
-	checks    map[string]Check
-	startTime time.Time
+	server     *http.Server
+	mu         sync.RWMutex
+	ready      bool
+	checks     map[string]Check
+	startTime  time.Time
+	reloadFunc func() error
 }

 type Check struct {
@ -43,6 +44,7 @@ func NewServer(host string, port int) *Server {

 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
+	mux.HandleFunc("/reload", s.reloadHandler)

 	addr := fmt.Sprintf("%s:%d", host, port)
 	s.server = &http.Server{
@ -106,6 +108,44 @@ func (s *Server) RegisterCheck(name string, checkFn func() (bool, string)) {
 	}
 }

+// SetReloadFunc sets the callback function for config reload.
+func (s *Server) SetReloadFunc(fn func() error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.reloadFunc = fn
+}
+
+func (s *Server) reloadHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusMethodNotAllowed)
+		json.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
+		return
+	}
+
+	s.mu.Lock()
+	reloadFunc := s.reloadFunc
+	s.mu.Unlock()
+
+	if reloadFunc == nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusServiceUnavailable)
+		json.NewEncoder(w).Encode(map[string]string{"error": "reload not configured"})
+		return
+	}
+
+	if err := reloadFunc(); err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]string{"status": "reload triggered"})
+}
+
 func (s *Server) healthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
@ -158,11 +198,12 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	})
 }

-// RegisterOnMux registers /health and /ready handlers onto the given mux.
+// RegisterOnMux registers /health, /ready and /reload handlers onto the given mux.
 // This allows the health endpoints to be served by a shared HTTP server.
 func (s *Server) RegisterOnMux(mux *http.ServeMux) {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
+	mux.HandleFunc("/reload", s.reloadHandler)
 }

 func statusString(ok bool) string {
--- a/pkg/providers/model_ref.go
+++ b/pkg/providers/model_ref.go
@ -53,6 +53,14 @@ func NormalizeProvider(provider string) string {
 		return "zhipu"
 	case "google":
 		return "gemini"
+	case "alibaba-coding", "qwen-coding":
+		return "coding-plan"
+	case "alibaba-coding-anthropic":
+		return "coding-plan-anthropic"
+	case "qwen-international", "dashscope-intl":
+		return "qwen-intl"
+	case "dashscope-us":
+		return "qwen-us"
 	}

 	return p
--- a/pkg/providers/model_ref_test.go
+++ b/pkg/providers/model_ref_test.go
@ -73,6 +73,14 @@ func TestNormalizeProvider(t *testing.T) {
 		{"glm", "zhipu"},
 		{"google", "gemini"},
 		{"groq", "groq"},
+		// Alibaba Coding Plan aliases
+		{"alibaba-coding", "coding-plan"},
+		{"qwen-coding", "coding-plan"},
+		{"alibaba-coding-anthropic", "coding-plan-anthropic"},
+		// Qwen international aliases
+		{"qwen-international", "qwen-intl"},
+		{"dashscope-intl", "qwen-intl"},
+		{"dashscope-us", "qwen-us"},
 		{"", ""},
 	}

--- a/pkg/tools/web.go
+++ b/pkg/tools/web.go
@ -16,12 +16,14 @@ import (
 	"sync/atomic"
 	"time"

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

 const (
-	userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+	userAgent       = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+	userAgentHonest = "picoclaw/%s (+https://github.com/sipeed/picoclaw; AI assistant bot)"

 	// HTTP client timeouts for web tool providers.

@ -1012,28 +1014,58 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		}
 	}

-	req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("failed to create request: %v", err))
+	doFetch := func(ua string) (*http.Response, []byte, error) {
+		req, reqErr := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
+		if reqErr != nil {
+			return nil, nil, fmt.Errorf("failed to create request: %w", reqErr)
+		}
+		req.Header.Set("User-Agent", ua)
+		resp, doErr := t.client.Do(req)
+		if doErr != nil {
+			return nil, nil, fmt.Errorf("request failed: %w", doErr)
+		}
+		resp.Body = http.MaxBytesReader(nil, resp.Body, t.fetchLimitBytes)
+
+		b, readErr := io.ReadAll(resp.Body)
+		return resp, b, readErr
 	}

-	req.Header.Set("User-Agent", userAgent)
-	resp, err := t.client.Do(req)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("request failed: %v", err))
+	resp, body, err := doFetch(userAgent)
+	if resp != nil && resp.Body != nil {
+		defer resp.Body.Close()
 	}

-	resp.Body = http.MaxBytesReader(nil, resp.Body, t.fetchLimitBytes)
-
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		var maxBytesErr *http.MaxBytesError
 		if errors.As(err, &maxBytesErr) {
 			return ErrorResult(fmt.Sprintf("failed to read response: size exceeded %d bytes limit", t.fetchLimitBytes))
 		}
-		return ErrorResult(fmt.Sprintf("failed to read response: %v", err))
+		return ErrorResult(err.Error())
+	}
+
+	// Cloudflare (and similar WAFs) signal bot challenges with 403 + cf-mitigated: challenge.
+	// Retry once with an honest User-Agent that identifies picoclaw, which some
+	// operators explicitly allow-list for AI assistants.
+	if resp.StatusCode == http.StatusForbidden && resp.Header.Get("Cf-Mitigated") == "challenge" {
+		logger.DebugCF("tool", "Cloudflare challenge detected, retrying with honest User-Agent",
+			map[string]any{"url": urlStr})
+		honestUA := fmt.Sprintf(userAgentHonest, config.Version)
+		resp2, body2, err2 := doFetch(honestUA)
+		if resp2 != nil && resp2.Body != nil {
+			defer resp2.Body.Close()
+		}
+
+		if err2 == nil {
+			resp, body = resp2, body2
+		} else {
+			var maxBytesErr *http.MaxBytesError
+			if errors.As(err2, &maxBytesErr) {
+				return ErrorResult(
+					fmt.Sprintf("failed to read response: size exceeded %d bytes limit", t.fetchLimitBytes),
+				)
+			}
+			return ErrorResult(err2.Error())
+		}
 	}

 	bodyStr := string(body)
@ -1103,7 +1135,7 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe

 	truncated := len(text) > maxChars
 	if truncated {
-		text = text[:maxChars]
+		text = text[:maxChars] + "\n[Content truncated due to size limit]"
 	}

 	result := map[string]any{
--- a/pkg/tools/web_test.go
+++ b/pkg/tools/web_test.go
@ -212,6 +212,132 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 	if truncated, ok := resultMap["truncated"].(bool); !ok || !truncated {
 		t.Errorf("Expected 'truncated' to be true in result")
 	}
+
+	// Text should end with the truncation notice
+	if text, ok := resultMap["text"].(string); ok {
+		if !strings.HasSuffix(text, "[Content truncated due to size limit]") {
+			t.Errorf("Expected text to end with truncation notice, got: %q", text[max(0, len(text)-60):])
+		}
+	}
+}
+
+// TestWebTool_WebFetch_TruncationNotice verifies the truncation notice is appended
+// for all content formats (text/plain, text/html, markdown, application/json).
+func TestWebTool_WebFetch_TruncationNotice(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	const truncationNotice = "[Content truncated due to size limit]"
+	const maxChars = 100
+
+	tests := []struct {
+		name        string
+		contentType string
+		body        string
+		format      string
+	}{
+		{
+			name:        "plain text",
+			contentType: "text/plain",
+			body:        strings.Repeat("a", 500),
+			format:      "plaintext",
+		},
+		{
+			name:        "html plaintext extractor",
+			contentType: "text/html",
+			body:        "<html><body>" + strings.Repeat("b", 500) + "</body></html>",
+			format:      "plaintext",
+		},
+		{
+			name:        "html markdown extractor",
+			contentType: "text/html",
+			body:        "<html><body>" + strings.Repeat("c", 500) + "</body></html>",
+			format:      "markdown",
+		},
+		{
+			name:        "json",
+			contentType: "application/json",
+			body:        `"` + strings.Repeat("d", 500) + `"`,
+			format:      "plaintext",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", tt.contentType)
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(tt.body))
+			}))
+			defer server.Close()
+
+			tool, err := NewWebFetchTool(maxChars, tt.format, testFetchLimit)
+			if err != nil {
+				t.Fatalf("NewWebFetchTool() error: %v", err)
+			}
+
+			result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+			if result.IsError {
+				t.Fatalf("unexpected error: %s", result.ForLLM)
+			}
+
+			var resultMap map[string]any
+			if err := json.Unmarshal([]byte(result.ForLLM), &resultMap); err != nil {
+				t.Fatalf("failed to unmarshal result JSON: %v", err)
+			}
+
+			text, ok := resultMap["text"].(string)
+			if !ok {
+				t.Fatal("missing 'text' field in result")
+			}
+
+			if !strings.HasSuffix(text, truncationNotice) {
+				t.Errorf("expected text to end with %q, got suffix: %q", truncationNotice, text[max(0, len(text)-60):])
+			}
+
+			if truncated, ok := resultMap["truncated"].(bool); !ok || !truncated {
+				t.Errorf("expected truncated=true in result")
+			}
+		})
+	}
+}
+
+// TestWebTool_WebFetch_NoTruncationNoticeWhenFitsInLimit verifies that the notice
+// is NOT appended when the content fits within the limit.
+func TestWebTool_WebFetch_NoTruncationNoticeWhenFitsInLimit(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	const truncationNotice = "[Content truncated due to size limit]"
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("short content"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+	if result.IsError {
+		t.Fatalf("unexpected error: %s", result.ForLLM)
+	}
+
+	var resultMap map[string]any
+	if err := json.Unmarshal([]byte(result.ForLLM), &resultMap); err != nil {
+		t.Fatalf("failed to unmarshal result JSON: %v", err)
+	}
+
+	text, _ := resultMap["text"].(string)
+	if strings.Contains(text, truncationNotice) {
+		t.Errorf("expected no truncation notice for content within limit, got: %q", text)
+	}
+
+	if truncated, _ := resultMap["truncated"].(bool); truncated {
+		t.Errorf("expected truncated=false for content within limit")
+	}
 }

 func TestWebFetchTool_PayloadTooLarge(t *testing.T) {
@ -943,6 +1069,119 @@ func TestWebTool_TavilySearch_Success(t *testing.T) {
 	}
 }

+// TestWebFetchTool_CloudflareChallenge_RetryWithHonestUA verifies that a 403 response
+// with cf-mitigated: challenge triggers a retry using the honest picoclaw User-Agent,
+// and that the retry response is returned when it succeeds.
+func TestWebFetchTool_CloudflareChallenge_RetryWithHonestUA(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	requestCount := 0
+	var receivedUAs []string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestCount++
+		receivedUAs = append(receivedUAs, r.Header.Get("User-Agent"))
+
+		if requestCount == 1 {
+			// First request: simulate Cloudflare challenge
+			w.Header().Set("Cf-Mitigated", "challenge")
+			w.Header().Set("Content-Type", "text/html")
+			w.WriteHeader(http.StatusForbidden)
+			w.Write([]byte("<html><body>Cloudflare challenge</body></html>"))
+			return
+		}
+		// Second request (honest UA retry): success
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("real content"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	if result.IsError {
+		t.Fatalf("expected success after retry, got error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "real content") {
+		t.Errorf("expected retry response content, got: %s", result.ForLLM)
+	}
+	if requestCount != 2 {
+		t.Errorf("expected exactly 2 requests, got %d", requestCount)
+	}
+
+	// First request must use the generic user agent
+	if receivedUAs[0] != userAgent {
+		t.Errorf("first request UA = %q, want %q", receivedUAs[0], userAgent)
+	}
+	// Second request must use the honest picoclaw user agent
+	if !strings.Contains(receivedUAs[1], "picoclaw") {
+		t.Errorf("retry request UA = %q, want it to contain 'picoclaw'", receivedUAs[1])
+	}
+}
+
+// TestWebFetchTool_CloudflareChallenge_NoRetryOnOtherErrors verifies that a plain 403
+// (without cf-mitigated: challenge) does NOT trigger a retry.
+func TestWebFetchTool_CloudflareChallenge_NoRetryOnOtherErrors(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	requestCount := 0
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestCount++
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte("plain forbidden"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	if requestCount != 1 {
+		t.Errorf("expected exactly 1 request for plain 403, got %d", requestCount)
+	}
+}
+
+// TestWebFetchTool_CloudflareChallenge_RetryFailsToo verifies that if the honest-UA
+// retry also fails (e.g. still blocked), the error from the retry is returned.
+func TestWebFetchTool_CloudflareChallenge_RetryFailsToo(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Always return CF challenge regardless of UA
+		w.Header().Set("Cf-Mitigated", "challenge")
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte("<html><body>still blocked</body></html>"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	// Should not be an error — the retry response is used as-is (403 is a valid HTTP response)
+	if result.IsError {
+		t.Fatalf("expected non-error result even when retry is also blocked, got: %s", result.ForLLM)
+	}
+	// Status in the JSON result should reflect the 403
+	if !strings.Contains(result.ForLLM, "403") {
+		t.Errorf("expected status 403 in result, got: %s", result.ForLLM)
+	}
+}
+
 func TestAPIKeyPool(t *testing.T) {
 	pool := NewAPIKeyPool([]string{"key1", "key2", "key3"})
 	if len(pool.keys) != 3 {
--- a/web/frontend/package.json
+++ b/web/frontend/package.json
@ -14,8 +14,8 @@
  },
  "dependencies": {
    "@fontsource-variable/inter": "^5.2.8",
-    "@tabler/icons-react": "^3.38.0",
-    "@tailwindcss/vite": "^4.2.1",
+    "@tabler/icons-react": "^3.40.0",
+    "@tailwindcss/vite": "^4.2.2",
    "@tanstack/react-query": "^5.90.21",
    "@tanstack/react-router": "^1.167.0",
    "@tanstack/react-router-devtools": "^1.163.3",
@ -32,32 +32,32 @@
    "react-markdown": "^10.1.0",
    "react-textarea-autosize": "^8.5.9",
    "remark-gfm": "^4.0.1",
-    "shadcn": "^4.0.5",
+    "shadcn": "^4.1.0",
    "sonner": "^2.0.7",
    "tailwind-merge": "^3.5.0",
-    "tailwindcss": "^4.2.1",
+    "tailwindcss": "^4.2.2",
    "tw-animate-css": "^1.4.0",
    "wrap-ansi": "^10.0.0"
  },
  "devDependencies": {
-    "@eslint/js": "^9.39.3",
+    "@eslint/js": "^9.39.4",
    "@tailwindcss/typography": "^0.5.19",
    "@tanstack/router-plugin": "^1.164.0",
    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.5.0",
    "@types/react": "^19.2.7",
    "@types/react-dom": "^19.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
    "@vitejs/plugin-react": "^5.2.0",
-    "eslint": "^9.39.3",
+    "eslint": "^9.39.4",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
+    "eslint-plugin-react-refresh": "^0.4.26",
    "globals": "^16.5.0",
    "prettier": "^3.8.1",
    "prettier-plugin-tailwindcss": "^0.7.2",
    "typescript": "~5.9.3",
-    "typescript-eslint": "^8.48.0",
+    "typescript-eslint": "^8.57.1",
    "vite": "^7.3.1"
  }
 }
--- a/web/frontend/pnpm-lock.yaml
+++ b/web/frontend/pnpm-lock.yaml
--- a/web/frontend/src/components/channels/channel-forms/generic-form.tsx
+++ b/web/frontend/src/components/channels/channel-forms/generic-form.tsx
@ -138,6 +138,7 @@ export function GenericForm({
      real_name: t("channels.form.desc.realName"),
      channels: t("channels.form.desc.channels"),
      request_caps: t("channels.form.desc.requestCaps"),
+      max_base64_file_size_mib: t("channels.form.desc.maxBase64FileSizeMiB"),
    }
    return (
      descriptions[key] ??
--- a/web/frontend/src/i18n/locales/en.json
+++ b/web/frontend/src/i18n/locales/en.json
@ -328,6 +328,7 @@
        "realName": "Displayed real name.",
        "channels": "IRC channels to join.",
        "requestCaps": "IRC capability list requested on connect.",
+        "maxBase64FileSizeMiB": "Maximum size in MiB for converting local files to base64 before upload. 0 means unlimited. Applies only to local files, not URL uploads.",
        "genericField": "Used to configure {{field}}."
      }
    },
--- a/web/frontend/src/i18n/locales/zh.json
+++ b/web/frontend/src/i18n/locales/zh.json
@ -328,6 +328,7 @@
        "realName": "显示名称。",
        "channels": "要加入的 IRC 频道列表。",
        "requestCaps": "连接时请求的 IRC 扩展能力列表。",
+        "maxBase64FileSizeMiB": "本地文件转为 base64 上传的最大体积，单位 MiB；0 表示不限制，仅影响本地文件，不影响 URL 直传。",
        "genericField": "用于配置{{field}}。"
      }
    },