Merge remote-tracking branch 'origin/main' into feat_discord_proxy

2026-08-01 01:26:19 +00:00 · 2026-03-02 18:17:51 +08:00
parent 9be6fb1a7d 26d1b8e374
commit 69b1ae48d5
181 changed files with 22003 additions and 3595 deletions
@@ -44,3 +44,6 @@ tasks/

 # Added by goreleaser init:
 dist/
+
+# Windows Application Icon/Resource
+*.syso
@@ -5,7 +5,9 @@ version: 2
 before:
  hooks:
    - go mod tidy
-    - go generate ./cmd/picoclaw/...
+    - go generate ./...
+    - go install github.com/tc-hib/go-winres@latest
+    - go-winres make --in cmd/picoclaw-launcher/winres/winres.json --out cmd/picoclaw-launcher/rsrc --product-version={{ .Version }} --file-version={{ .Version }}

 builds:
  - id: picoclaw
@@ -31,12 +33,67 @@ builds:
      - loong64
      - arm
    goarm:
-      - "7"             
+      - "6"
+      - "7"
    main: ./cmd/picoclaw
    ignore:
      - goos: windows
        goarch: arm

+  - id: picoclaw-launcher
+    binary: picoclaw-launcher
+    env:
+      - CGO_ENABLED=0
+    tags:
+      - stdjson
+    ldflags:
+      - -s -w
+    goos:
+      - linux
+      - windows
+      - darwin
+      - freebsd
+    goarch:
+      - amd64
+      - arm64
+      - riscv64
+      - loong64
+      - arm
+    goarm:
+      - "6"
+      - "7"
+    main: ./cmd/picoclaw-launcher
+    ignore:
+      - goos: windows
+        goarch: arm
+
+  - id: picoclaw-launcher-tui
+    binary: picoclaw-launcher-tui
+    env:
+      - CGO_ENABLED=0
+    tags:
+      - stdjson
+    ldflags:
+      - -s -w
+    goos:
+      - linux
+      - windows
+      - darwin
+      - freebsd
+    goarch:
+      - amd64
+      - arm64
+      - riscv64
+      - loong64
+      - arm
+    goarm:
+      - "6"
+      - "7"
+    main: ./cmd/picoclaw-launcher-tui
+    ignore:
+      - goos: windows
+        goarch: arm
+
 dockers_v2:
  - id: picoclaw
    dockerfile: docker/Dockerfile.goreleaser
@@ -72,6 +129,10 @@ archives:

 nfpms:
  - id: picoclaw
+    builds:
+      - picoclaw
+      - picoclaw-launcher
+      - picoclaw-launcher-tui
    package_name: picoclaw
    file_name_template: >-
      {{ .PackageName }}_
@@ -87,11 +87,46 @@ build: generate
 	@echo "Build complete: $(BINARY_PATH)"
 	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)

+## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
+build-whatsapp-native: generate
+## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."
+	@echo "Building for multiple platforms..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=loong64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=riscv64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+	GOOS=darwin GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
+	GOOS=windows GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+## @$(GO) build $(GOFLAGS) -tags whatsapp_native $(LDFLAGS) -o $(BINARY_PATH) ./$(CMD_DIR)
+	@echo "Build complete"
+##	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
+
+## build-linux-arm: Build for Linux ARMv7 (e.g. Raspberry Pi Zero 2 W 32-bit)
+build-linux-arm: generate
+	@echo "Building for linux/arm (GOARM=7)..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm"
+
+## build-linux-arm64: Build for Linux ARM64 (e.g. Raspberry Pi Zero 2 W 64-bit)
+build-linux-arm64: generate
+	@echo "Building for linux/arm64..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64"
+
+## build-pi-zero: Build for Raspberry Pi Zero 2 W (32-bit and 64-bit)
+build-pi-zero: build-linux-arm build-linux-arm64
+	@echo "Pi Zero 2 W builds: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm (32-bit), $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 (64-bit)"
+
 ## build-all: Build picoclaw for all platforms
 build-all: generate
 	@echo "Building for multiple platforms..."
 	@mkdir -p $(BUILD_DIR)
 	GOOS=linux GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
 	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
 	GOOS=linux GOARCH=loong64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
 	GOOS=linux GOARCH=riscv64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
@@ -456,8 +456,6 @@ picoclaw gateway
      "enabled": true,
      "channel_secret": "VOTRE_CHANNEL_SECRET",
      "channel_access_token": "VOTRE_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -470,12 +468,14 @@ picoclaw gateway
 LINE exige HTTPS pour les webhooks. Utilisez un reverse proxy ou un tunnel :

 ```bash
-# Exemple avec ngrok
-ngrok http 18791
+# Exemple avec ngrok (tunnel vers le serveur Gateway partagé)
+ngrok http 18790
 ```

 Puis configurez l'URL du Webhook dans la LINE Developers Console sur `https://votre-domaine/webhook/line` et activez **Use webhook**.

+> **Note** : Le webhook LINE est servi par le serveur Gateway partagé (par défaut `127.0.0.1:18790`). Si vous utilisez ngrok ou un proxy inverse, faites pointer le tunnel vers le port `18790`.
+
 **4. Lancer**

 ```bash
@@ -484,7 +484,7 @@ picoclaw gateway

 > Dans les discussions de groupe, le bot répond uniquement lorsqu'il est mentionné avec @. Les réponses citent le message original.

-> **Docker Compose** : Ajoutez `ports: ["18791:18791"]` au service `picoclaw-gateway` pour exposer le port du webhook.
+> **Docker Compose** : Si vous avez besoin d'exposer le webhook LINE via Docker, mappez le port du Gateway partagé (par défaut `18790`) vers l'hôte, par exemple `ports: ["18790:18790"]`. Notez que le serveur Gateway sert les webhooks de tous les canaux à partir de ce port.

 </details>

@@ -515,8 +515,6 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
@@ -535,7 +533,7 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
 **2. Configurer la réception des messages**

 * Dans les détails de l'application, cliquez sur "Recevoir les Messages" → "Configurer l'API"
-* Définissez l'URL sur `http://your-server:18792/webhook/wecom-app`
+* Définissez l'URL sur `http://your-server:18790/webhook/wecom-app`
 * Générez le **Token** et l'**EncodingAESKey**

 **3. Configurer**
@@ -550,8 +548,6 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
@@ -565,7 +561,7 @@ Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour
 picoclaw gateway
 ```

-> **Note** : WeCom App nécessite l'ouverture du port 18792 pour les callbacks webhook. Utilisez un proxy inverse pour HTTPS en production.
+> **Note** : Les callbacks webhook WeCom App sont servis par le serveur Gateway partagé (par défaut `127.0.0.1:18790`). Assurez-vous que le port `18790` est accessible ou utilisez un proxy inverse HTTPS en production.

 </details>

@@ -579,6 +575,31 @@ Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul mes

 Fichier de configuration : `~/.picoclaw/config.json`

+### Variables d'Environnement
+
+Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de picoclaw en tant que service système. Ces variables sont indépendantes et contrôlent différents chemins.
+
+| Variable          | Description                                                                                                                             | Chemin par Défaut         |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Remplace le chemin du fichier de configuration. Cela indique directement à picoclaw quel `config.json` charger, en ignorant tous les autres emplacements. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Remplace le répertoire racine des données picoclaw. Cela modifie l'emplacement par défaut du `workspace` et des autres répertoires de données.          | `~/.picoclaw`             |
+
+**Exemples :**
+
+```bash
+# Exécuter picoclaw en utilisant un fichier de configuration spécifique
+# Le chemin du workspace sera lu à partir de ce fichier de configuration
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Exécuter picoclaw avec toutes ses données stockées dans /opt/picoclaw
+# La configuration sera chargée à partir du fichier par défaut ~/.picoclaw/config.json
+# Le workspace sera créé dans /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Utiliser les deux pour une configuration entièrement personnalisée
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### Structure du Workspace

 PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.picoclaw/workspace`) :
@@ -421,8 +421,6 @@ picoclaw gateway
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -436,11 +434,13 @@ LINE の Webhook には HTTPS が必要です。リバースプロキシまた

 ```bash
 # ngrok の例
-ngrok http 18791
+ngrok http 18790
 ```

 LINE Developers Console で Webhook URL を `https://あなたのドメイン/webhook/line` に設定し、**Webhook の利用** を有効にしてください。

+> **注意**: LINE の Webhook は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、リバースプロキシを設定してください。
+
 **4. 起動**

 ```bash
@@ -449,7 +449,7 @@ picoclaw gateway

 > グループチャットでは @メンション時のみ応答します。返信は元メッセージを引用する形式です。

-> **Docker Compose**: `picoclaw-gateway` サービスに `ports: ["18791:18791"]` を追加して Webhook ポートを公開してください。
+> **Docker Compose**: Gateway HTTP サーバーは共有の `127.0.0.1:18790` で Webhook を提供します。ホストからアクセスするには `picoclaw-gateway` サービスに `ports: ["18790:18790"]` を追加してください。

 </details>

@@ -480,13 +480,13 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
 }
+
+> **注意**: WeCom Bot の Webhook 受信は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、HTTPS 用のリバースプロキシを設定してください。
 ```

 **クイックセットアップ - WeCom App:**
@@ -500,7 +500,7 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
 **2. メッセージ受信を設定**

 * アプリ詳細で "メッセージを受信" → "APIを設定" をクリック
-* URL を `http://your-server:18792/webhook/wecom-app` に設定
+* URL を `http://your-server:18790/webhook/wecom-app` に設定
 * **Token** と **EncodingAESKey** を生成

 **3. 設定**
@@ -515,8 +515,6 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
@@ -530,7 +528,7 @@ PicoClaw は2種類の WeCom 統合をサポートしています：
 picoclaw gateway
 ```

-> **注意**: WeCom App は Webhook コールバック用にポート 18792 を開放する必要があります。本番環境では HTTPS 用のリバースプロキシを使用してください。
+> **注意**: WeCom App の Webhook コールバックは共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は HTTPS 用のリバースプロキシを設定してください。

 </details>

@@ -538,6 +536,31 @@ picoclaw gateway

 設定ファイル: `~/.picoclaw/config.json`

+### 環境変数
+
+環境変数を使用してデフォルトのパスを上書きできます。これは、ポータブルインストール、コンテナ化されたデプロイメント、または picoclaw をシステムサービスとして実行する場合に便利です。これらの変数は独立しており、異なるパスを制御します。
+
+| 変数              | 説明                                                                                                                             | デフォルトパス            |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | 設定ファイルへのパスを上書きします。これにより、picoclaw は他のすべての場所を無視して、指定された `config.json` をロードします。 | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | picoclaw データのルートディレクトリを上書きします。これにより、`workspace` やその他のデータディレクトリのデフォルトの場所が変更されます。          | `~/.picoclaw`             |
+
+**例：**
+
+```bash
+# 特定の設定ファイルを使用して picoclaw を実行する
+# ワークスペースのパスはその設定ファイル内から読み込まれます
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# すべてのデータを /opt/picoclaw に保存して picoclaw を実行する
+# 設定はデフォルトの ~/.picoclaw/config.json からロードされます
+# ワークスペースは /opt/picoclaw/workspace に作成されます
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# 両方を使用して完全にカスタマイズされたセットアップを行う
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### ワークスペース構成

 PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw/workspace`）にデータを保存します：
@@ -154,10 +154,15 @@ make build
 # Build for multiple platforms
 make build-all

+# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
 # Build And Install
 make install
 ```

+**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS → `make build-linux-arm` (output: `build/picoclaw-linux-arm`); 64-bit → `make build-linux-arm64` (output: `build/picoclaw-linux-arm64`). Or run `make build-pi-zero` to build both.
+
 ## 🐳 Docker Compose

 You can also run PicoClaw using Docker Compose without installing anything locally.
@@ -288,12 +293,15 @@ That's it! You have a working AI assistant in 2 minutes.

 ## 💬 Chat Apps

-Talk to your picoclaw through Telegram, Discord, DingTalk, LINE, or WeCom
+Talk to your picoclaw through Telegram, Discord, WhatsApp, 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) |
 | **QQ**       | Easy (AppID + AppSecret)           |
 | **DingTalk** | Medium (app credentials)           |
 | **LINE**     | Medium (credentials + webhook URL) |
@@ -358,8 +366,7 @@ picoclaw gateway
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"],
-      "mention_only": false
+      "allow_from": ["YOUR_USER_ID"]
    }
  }
 }
@@ -372,9 +379,31 @@ picoclaw gateway
 * Bot Permissions: `Send Messages`, `Read Message History`
 * Open the generated invite URL and add the bot to your server

-**Optional: Mention-only mode**
+**Optional: Group trigger mode**

-Set `"mention_only": true` to make the bot respond only when @-mentioned. Useful for shared servers where you want the bot to respond only when explicitly called.
+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**

@@ -384,6 +413,33 @@ 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>

@@ -468,8 +524,6 @@ picoclaw gateway
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -477,13 +531,15 @@ picoclaw gateway
 }
 ```

+> 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
-ngrok http 18791
+# 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**.
@@ -496,8 +552,6 @@ picoclaw gateway

 > In group chats, the bot responds only when @mentioned. Replies quote the original message.

-> **Docker Compose**: Add `ports: ["18791:18791"]` to the `picoclaw-gateway` service to expose the webhook port.
-
 </details>

 <details>
@@ -527,8 +581,6 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
@@ -536,6 +588,8 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 }
 ```

+> WeCom webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
+
 **Quick Setup - WeCom App:**

 **1. Create an app**
@@ -543,10 +597,11 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 * Go to WeCom Admin Console → App Management → Create App
 * Copy **AgentId** and **Secret**
 * Go to "My Company" page, copy **CorpID**
+
 **2. Configure receive message**

 * In App details, click "Receive Message" → "Set API"
-* Set URL to `http://your-server:18792/webhook/wecom-app`
+* Set URL to `http://your-server:18790/webhook/wecom-app`
 * Generate **Token** and **EncodingAESKey**

 **3. Configure**
@@ -561,8 +616,6 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
@@ -576,7 +629,7 @@ See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detaile
 picoclaw gateway
 ```

-> **Note**: WeCom App requires opening port 18792 for webhook callbacks. Use a reverse proxy for HTTPS.
+> **Note**: WeCom webhook callbacks are served on the Gateway port (default 18790). Use a reverse proxy for HTTPS.

 </details>

@@ -590,6 +643,31 @@ Connect Picoclaw to the Agent Social Network simply by sending a single message

 Config file: `~/.picoclaw/config.json`

+### Environment Variables
+
+You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths.
+
+| Variable          | Description                                                                                                                             | Default Path              |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Overrides the path to the configuration file. This directly tells picoclaw which `config.json` to load, ignoring all other locations. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Overrides the root directory for picoclaw data. This changes the default location of the `workspace` and other data directories.          | `~/.picoclaw`             |
+
+**Examples:**
+
+```bash
+# Run picoclaw using a specific config file
+# The workspace path will be read from within that config file
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Run picoclaw with all its data stored in /opt/picoclaw
+# Config will be loaded from the default ~/.picoclaw/config.json
+# Workspace will be created at /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Use both for a fully customized setup
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### Workspace Layout

 PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
@@ -1070,7 +1148,11 @@ picoclaw agent -m "Hello"
      "allow_from": [""]
    },
    "whatsapp": {
-      "enabled": false
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
    },
    "feishu": {
      "enabled": false,
@@ -450,8 +450,6 @@ picoclaw gateway
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -465,11 +463,13 @@ O LINE requer HTTPS para webhooks. Use um reverse proxy ou tunnel:

 ```bash
 # Exemplo com ngrok
-ngrok http 18791
+ngrok http 18790
 ```

 Em seguida, configure a Webhook URL no LINE Developers Console para `https://seu-dominio/webhook/line` e habilite **Use webhook**.

+> **Nota**: O webhook do LINE é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel (como ngrok) para expor o Gateway de forma segura quando necessário.
+
 **4. Executar**

 ```bash
@@ -478,7 +478,7 @@ picoclaw gateway

 > Em chats de grupo, o bot responde apenas quando mencionado com @. As respostas citam a mensagem original.

-> **Docker Compose**: Adicione `ports: ["18791:18791"]` ao serviço `picoclaw-gateway` para expor a porta do webhook.
+> **Docker Compose**: Se você usa Docker Compose, exponha o Gateway (padrão 127.0.0.1:18790) se precisar acessar o webhook LINE externamente, por exemplo `ports: ["18790:18790"]`.

 </details>

@@ -509,8 +509,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
@@ -518,6 +516,8 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 }
 ```

+> **Nota**: O webhook do WeCom Bot é atendido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel para expor o Gateway em produção.
+
 **Configuração Rápida - WeCom App:**

 **1. Criar um aplicativo**
@@ -529,7 +529,7 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 **2. Configurar recebimento de mensagens**

 * Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API"
-* Defina a URL como `http://your-server:18792/webhook/wecom-app`
+* Defina a URL como `http://your-server:18790/webhook/wecom-app`
 * Gere o **Token** e o **EncodingAESKey**

 **3. Configurar**
@@ -544,8 +544,6 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
@@ -559,7 +557,7 @@ Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para
 picoclaw gateway
 ```

-> **Nota**: O WeCom App requer a abertura da porta 18792 para callbacks de webhook. Use um proxy reverso para HTTPS em produção.
+> **Nota**: O WeCom App (callbacks de webhook) é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Em produção use um proxy reverso HTTPS para expor a porta do Gateway, ou atualize `PICOCLAW_GATEWAY_HOST` para `0.0.0.0` se necessário.

 </details>

@@ -573,6 +571,31 @@ Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única men

 Arquivo de configuração: `~/.picoclaw/config.json`

+### Variáveis de Ambiente
+
+Você pode substituir os caminhos padrão usando variáveis de ambiente. Isso é útil para instalações portáteis, implantações em contêineres ou para executar o picoclaw como um serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.
+
+| Variável          | Descrição                                                                                                                             | Caminho Padrão            |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Substitui o caminho para o arquivo de configuração. Isso informa diretamente ao picoclaw qual `config.json` carregar, ignorando todos os outros locais. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Substitui o diretório raiz dos dados do picoclaw. Isso altera o local padrão do `workspace` e de outros diretórios de dados.          | `~/.picoclaw`             |
+
+**Exemplos:**
+
+```bash
+# Executar o picoclaw usando um arquivo de configuração específico
+# O caminho do workspace será lido de dentro desse arquivo de configuração
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Executar o picoclaw com todos os seus dados armazenados em /opt/picoclaw
+# A configuração será carregada do ~/.picoclaw/config.json padrão
+# O workspace será criado em /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Use ambos para uma configuração totalmente personalizada
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### Estrutura do Workspace

 O PicoClaw armazena dados no workspace configurado (padrão: `~/.picoclaw/workspace`):
@@ -3,7 +3,7 @@

 <h1>PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go</h1>

-<h3>Phần cứng $10 · RAM 10MB · Khởi động 1 giây · 皮皮虾，我们走！</h3>
+<h3>Phần cứng $10 · RAM 10MB · Khởi động 1 giây · Nào, xuất phát!</h3>

  <p>
    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
@@ -424,8 +424,6 @@ picoclaw gateway
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -439,7 +437,7 @@ LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel:

 ```bash
 # Ví dụ với ngrok
-ngrok http 18791
+ngrok http 18790
 ```

 Sau đó cài đặt Webhook URL trong LINE Developers Console thành `https://your-domain/webhook/line` và bật **Use webhook**.
@@ -452,7 +450,7 @@ picoclaw gateway

 > Trong nhóm chat, bot chỉ phản hồi khi được @mention. Các câu trả lời sẽ trích dẫn tin nhắn gốc.

-> **Docker Compose**: Thêm `ports: ["18791:18791"]` vào service `picoclaw-gateway` để mở port webhook.
+> **Docker Compose**: Nếu bạn cần mở port webhook cục bộ, hãy thêm một rule chuyển tiếp từ port Gateway (mặc định 18790) tới host. Lưu ý: LINE webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790).

 </details>

@@ -483,8 +481,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
@@ -492,6 +488,8 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 }
 ```

+> **Lưu ý:** Các endpoint webhook của WeCom Bot được phục vụ bởi máy chủ Gateway HTTP dùng chung (mặc định 127.0.0.1:18790). Nếu bạn cần truy cập từ bên ngoài, hãy cấu hình reverse proxy hoặc mở cổng Gateway tương ứng.
+
 **Thiết lập Nhanh - WeCom App:**

 **1. Tạo ứng dụng**
@@ -503,7 +501,7 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 **2. Cấu hình nhận tin nhắn**

 * Trong chi tiết ứng dụng, nhấp vào "Nhận Tin nhắn" → "Thiết lập API"
-* Đặt URL thành `http://your-server:18792/webhook/wecom-app`
+* Đặt URL thành `http://your-server:18790/webhook/wecom-app`
 * Tạo **Token** và **EncodingAESKey**

 **3. Cấu hình**
@@ -518,8 +516,6 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
@@ -533,7 +529,7 @@ Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) đ
 picoclaw gateway
 ```

-> **Lưu ý**: WeCom App yêu cầu mở cổng 18792 cho callback webhook. Sử dụng proxy ngược cho HTTPS trong môi trường sản xuất.
+> **Lưu ý**: WeCom App callback webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790). Sử dụng proxy ngược để cung cấp HTTPS trong môi trường production nếu cần.

 </details>

@@ -547,6 +543,31 @@ Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một

 File cấu hình: `~/.picoclaw/config.json`

+### Biến môi trường
+
+Bạn có thể ghi đè các đường dẫn mặc định bằng cách sử dụng các biến môi trường. Điều này hữu ích cho việc cài đặt di động, triển khai container hóa hoặc chạy picoclaw như một dịch vụ hệ thống. Các biến này độc lập và kiểm soát các đường dẫn khác nhau.
+
+| Biến              | Mô tả                                                                                                                             | Đường dẫn mặc định        |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Ghi đè đường dẫn đến file cấu hình. Điều này trực tiếp yêu cầu picoclaw tải file `config.json` nào, bỏ qua tất cả các vị trí khác. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Ghi đè thư mục gốc cho dữ liệu picoclaw. Điều này thay đổi vị trí mặc định của `workspace` và các thư mục dữ liệu khác.          | `~/.picoclaw`             |
+
+**Ví dụ:**
+
+```bash
+# Chạy picoclaw bằng một file cấu hình cụ thể
+# Đường dẫn workspace sẽ được đọc từ trong file cấu hình đó
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Chạy picoclaw với tất cả dữ liệu được lưu trữ trong /opt/picoclaw
+# Cấu hình sẽ được tải từ ~/.picoclaw/config.json mặc định
+# Workspace sẽ được tạo tại /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Sử dụng cả hai để có thiết lập tùy chỉnh hoàn toàn
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### Cấu trúc Workspace

 PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`):
@@ -290,6 +290,8 @@ picoclaw agent -m "2+2 等于几？"

 PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。

+> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。
+
 ### 核心渠道

 | 渠道                 | 设置难度    | 特性说明                                  | 文档链接                                                                                                        |
@@ -315,6 +317,31 @@ PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方

 配置文件路径: `~/.picoclaw/config.json`

+### 环境变量
+
+你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
+
+| 变量              | 描述                                                                                                                             | 默认路径                  |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。          | `~/.picoclaw`             |
+
+**示例：**
+
+```bash
+# 使用特定的配置文件运行 picoclaw
+# 工作区路径将从该配置文件中读取
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
+# 配置将从默认的 ~/.picoclaw/config.json 加载
+# 工作区将在 /opt/picoclaw/workspace 创建
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# 同时使用两者进行完全自定义设置
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
 ### 工作区布局 (Workspace Layout)

 PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
@@ -0,0 +1,49 @@
+package configstore
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+
+	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
+)
+
+const (
+	configDirName  = ".picoclaw"
+	configFileName = "config.json"
+)
+
+func ConfigPath() (string, error) {
+	dir, err := ConfigDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, configFileName), nil
+}
+
+func ConfigDir() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(home, configDirName), nil
+}
+
+func Load() (*picoclawconfig.Config, error) {
+	path, err := ConfigPath()
+	if err != nil {
+		return nil, err
+	}
+	return picoclawconfig.LoadConfig(path)
+}
+
+func Save(cfg *picoclawconfig.Config) error {
+	if cfg == nil {
+		return errors.New("config is nil")
+	}
+	path, err := ConfigPath()
+	if err != nil {
+		return err
+	}
+	return picoclawconfig.SaveConfig(path, cfg)
+}
@@ -0,0 +1,506 @@
+package ui
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	configstore "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/config"
+	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
+)
+
+type appState struct {
+	app         *tview.Application
+	pages       *tview.Pages
+	stack       []string
+	config      *picoclawconfig.Config
+	configPath  string
+	gatewayCmd  *exec.Cmd
+	menus       map[string]*Menu
+	original    []byte
+	hasOriginal bool
+	backupPath  string
+	dirty       bool
+	logPath     string
+}
+
+func Run() error {
+	applyStyles()
+	cfg, err := configstore.Load()
+	if err != nil {
+		return err
+	}
+	path, err := configstore.ConfigPath()
+	if err != nil {
+		return err
+	}
+
+	if cfg == nil {
+		cfg = picoclawconfig.DefaultConfig()
+	}
+
+	originalData, hasOriginal := loadOriginalConfig(path)
+	backupPath := path + ".bak"
+	if hasOriginal {
+		_ = writeBackupConfig(backupPath, originalData)
+	}
+
+	logPath := filepath.Join(filepath.Dir(path), "gateway.log")
+	state := &appState{
+		app:         tview.NewApplication(),
+		pages:       tview.NewPages(),
+		config:      cfg,
+		configPath:  path,
+		menus:       map[string]*Menu{},
+		original:    originalData,
+		hasOriginal: hasOriginal,
+		backupPath:  backupPath,
+		logPath:     logPath,
+	}
+
+	state.push("main", state.mainMenu())
+
+	root := tview.NewFlex().SetDirection(tview.FlexRow)
+	root.AddItem(bannerView(), 6, 0, false)
+	root.AddItem(state.pages, 0, 1, true)
+
+	if err := state.app.SetRoot(root, true).EnableMouse(false).Run(); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *appState) push(name string, primitive tview.Primitive) {
+	s.pages.AddPage(name, primitive, true, true)
+	s.stack = append(s.stack, name)
+	s.pages.SwitchToPage(name)
+	if menu, ok := primitive.(*Menu); ok {
+		s.menus[name] = menu
+	}
+}
+
+func (s *appState) pop() {
+	if len(s.stack) == 0 {
+		return
+	}
+	last := s.stack[len(s.stack)-1]
+	s.pages.RemovePage(last)
+	s.stack = s.stack[:len(s.stack)-1]
+	if len(s.stack) == 0 {
+		s.app.Stop()
+		return
+	}
+	current := s.stack[len(s.stack)-1]
+	s.pages.SwitchToPage(current)
+	if menu, ok := s.menus[current]; ok {
+		s.refreshMenu(current, menu)
+	}
+}
+
+func (s *appState) mainMenu() tview.Primitive {
+	menu := NewMenu("Config Menu", nil)
+	refreshMainMenu(menu, s)
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		switch event.Key() {
+		case tcell.KeyEsc:
+			s.requestExit()
+			return nil
+		}
+		if event.Rune() == 'q' {
+			s.requestExit()
+			return nil
+		}
+		return event
+	})
+
+	return menu
+}
+
+func (s *appState) refreshMenu(name string, menu *Menu) {
+	switch name {
+	case "main":
+		refreshMainMenu(menu, s)
+	case "model":
+		refreshModelMenuFromState(menu, s)
+	case "channel":
+		refreshChannelMenuFromState(menu, s)
+	}
+}
+
+func refreshMainMenuIfPresent(s *appState) {
+	if menu, ok := s.menus["main"]; ok {
+		refreshMainMenu(menu, s)
+	}
+}
+
+func refreshMainMenu(menu *Menu, s *appState) {
+	selectedModel := s.selectedModelName()
+	modelReady := selectedModel != ""
+	channelReady := s.hasEnabledChannel()
+	gatewayRunning := s.gatewayCmd != nil || s.isGatewayRunning()
+
+	gatewayLabel := "Start Gateway"
+	gatewayDescription := "Launch gateway for channels"
+	if gatewayRunning {
+		gatewayLabel = "Stop Gateway"
+		gatewayDescription = "Gateway running"
+	}
+
+	items := []MenuItem{
+		{
+			Label:       rootModelLabel(selectedModel),
+			Description: rootModelDescription(selectedModel),
+			Action: func() {
+				s.push("model", s.modelMenu())
+			},
+			MainColor: func() *tcell.Color {
+				if modelReady {
+					return nil
+				}
+				color := tcell.ColorGray
+				return &color
+			}(),
+		},
+		{
+			Label:       rootChannelLabel(channelReady),
+			Description: rootChannelDescription(channelReady),
+			Action: func() {
+				s.push("channel", s.channelMenu())
+			},
+			MainColor: func() *tcell.Color {
+				if channelReady {
+					return nil
+				}
+				color := tcell.ColorGray
+				return &color
+			}(),
+		},
+		{
+			Label:       "Start Talk",
+			Description: "Open picoclaw agent in terminal",
+			Action: func() {
+				s.requestStartTalk()
+			},
+			Disabled: !modelReady,
+		},
+		{
+			Label:       gatewayLabel,
+			Description: gatewayDescription,
+			Action: func() {
+				if gatewayRunning {
+					s.stopGateway()
+				} else {
+					s.requestStartGateway()
+				}
+				refreshMainMenu(menu, s)
+			},
+			Disabled: !gatewayRunning && (!modelReady || !channelReady),
+		},
+		{
+			Label:       "View Gateway Log",
+			Description: "Open gateway.log",
+			Action: func() {
+				s.viewGatewayLog()
+			},
+		},
+		{
+			Label:       "Exit",
+			Description: "Exit the TUI",
+			Action: func() {
+				s.requestExit()
+			},
+		},
+	}
+	menu.applyItems(items)
+}
+
+func (s *appState) applyChangesValidated() bool {
+	if err := s.config.ValidateModelList(); err != nil {
+		s.showMessage("Validation failed", err.Error())
+		return false
+	}
+	if err := s.validateAgentModel(); err != nil {
+		s.showMessage("Validation failed", err.Error())
+		return false
+	}
+	if err := configstore.Save(s.config); err != nil {
+		s.showMessage("Save failed", err.Error())
+		return false
+	}
+	if data, err := os.ReadFile(s.configPath); err == nil {
+		s.original = data
+		s.hasOriginal = true
+		_ = writeBackupConfig(s.backupPath, data)
+	}
+	return true
+}
+
+func (s *appState) requestExit() {
+	if s.dirty {
+		s.confirmApplyOrDiscard(func() {
+			s.app.Stop()
+		}, func() {
+			s.discardChanges()
+			s.app.Stop()
+		})
+		return
+	}
+	s.app.Stop()
+}
+
+func (s *appState) requestStartTalk() {
+	if s.dirty {
+		s.confirmApplyOrDiscard(func() {
+			s.startTalk()
+		}, func() {
+			s.startTalk()
+		})
+		return
+	}
+	s.startTalk()
+}
+
+func (s *appState) requestStartGateway() {
+	if s.dirty {
+		s.confirmApplyOrDiscard(func() {
+			s.startGateway()
+		}, func() {
+			s.startGateway()
+		})
+		return
+	}
+	s.startGateway()
+}
+
+func (s *appState) viewGatewayLog() {
+	data, err := os.ReadFile(s.logPath)
+	if err != nil {
+		s.showMessage("Log not found", "gateway.log not found")
+		return
+	}
+	text := tview.NewTextView()
+	text.SetBorder(true).SetTitle("Gateway Log")
+	text.SetText(string(data))
+	text.SetDoneFunc(func(key tcell.Key) {
+		s.pages.RemovePage("log")
+	})
+	text.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pages.RemovePage("log")
+			return nil
+		}
+		return event
+	})
+	s.pages.AddPage("log", text, true, true)
+}
+
+func (s *appState) selectedModelName() string {
+	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
+	if modelName == "" {
+		return ""
+	}
+	if !s.isActiveModelValid() {
+		return ""
+	}
+	return modelName
+}
+
+func rootModelLabel(selected string) string {
+	if selected == "" {
+		return "Model (no model selected)"
+	}
+	return "Model (" + selected + ")"
+}
+
+func rootModelDescription(selected string) string {
+	if selected == "" {
+		return "no model selected"
+	}
+	return "selected"
+}
+
+func rootChannelLabel(valid bool) string {
+	if !valid {
+		return "Channel (no channel enabled)"
+	}
+	return "Channel"
+}
+
+func rootChannelDescription(valid bool) string {
+	if !valid {
+		return "no channel enabled"
+	}
+	return "enabled"
+}
+
+func (s *appState) startTalk() {
+	if !s.isActiveModelValid() {
+		s.showMessage("Model required", "Select a valid model before starting talk")
+		return
+	}
+	if !s.applyChangesValidated() {
+		return
+	}
+	s.app.Suspend(func() {
+		cmd := exec.Command("picoclaw", "agent")
+		cmd.Stdin = os.Stdin
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		_ = cmd.Run()
+	})
+}
+
+func (s *appState) startGateway() {
+	if !s.isActiveModelValid() {
+		s.showMessage("Model required", "Select a valid model before starting gateway")
+		return
+	}
+	if !s.hasEnabledChannel() {
+		s.showMessage("Channel required", "Enable at least one channel before starting gateway")
+		return
+	}
+	if !s.applyChangesValidated() {
+		return
+	}
+	_ = stopGatewayProcess()
+	cmd := exec.Command("picoclaw", "gateway")
+	logFile, err := os.OpenFile(s.logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		s.showMessage("Gateway failed", err.Error())
+		return
+	}
+	cmd.Stdout = logFile
+	cmd.Stderr = logFile
+	if err := cmd.Start(); err != nil {
+		s.showMessage("Gateway failed", err.Error())
+		_ = logFile.Close()
+		return
+	}
+	_ = logFile.Close()
+	s.gatewayCmd = cmd
+}
+
+func (s *appState) stopGateway() {
+	_ = stopGatewayProcess()
+	if s.gatewayCmd != nil && s.gatewayCmd.Process != nil {
+		_ = s.gatewayCmd.Process.Kill()
+	}
+	s.gatewayCmd = nil
+}
+
+func (s *appState) isGatewayRunning() bool {
+	return isGatewayProcessRunning()
+}
+
+func (s *appState) validateAgentModel() error {
+	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
+	if modelName == "" {
+		return nil
+	}
+	_, err := s.config.GetModelConfig(modelName)
+	return err
+}
+
+func (s *appState) isActiveModelValid() bool {
+	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
+	if modelName == "" {
+		return false
+	}
+	cfg, err := s.config.GetModelConfig(modelName)
+	if err != nil {
+		return false
+	}
+	hasKey := strings.TrimSpace(cfg.APIKey) != "" || strings.TrimSpace(cfg.AuthMethod) == "oauth"
+	hasModel := strings.TrimSpace(cfg.Model) != ""
+	return hasKey && hasModel
+}
+
+func (s *appState) hasEnabledChannel() bool {
+	c := s.config.Channels
+	return c.Telegram.Enabled || c.Discord.Enabled || c.QQ.Enabled || c.MaixCam.Enabled ||
+		c.WhatsApp.Enabled || c.Feishu.Enabled || c.DingTalk.Enabled || c.Slack.Enabled ||
+		c.LINE.Enabled || c.OneBot.Enabled || c.WeCom.Enabled || c.WeComApp.Enabled
+}
+
+func (s *appState) confirmApplyOrDiscard(onApply func(), onDiscard func()) {
+	if s.pages.HasPage("apply") {
+		return
+	}
+	modal := tview.NewModal().
+		SetText("Apply changes or discard before continuing?").
+		AddButtons([]string{"Cancel", "Discard", "Apply"}).
+		SetDoneFunc(func(buttonIndex int, buttonLabel string) {
+			s.pages.RemovePage("apply")
+			switch buttonLabel {
+			case "Discard":
+				s.discardChanges()
+				if onDiscard != nil {
+					onDiscard()
+				}
+			case "Apply":
+				if s.applyChangesValidated() {
+					s.dirty = false
+					if onApply != nil {
+						onApply()
+					}
+				}
+			}
+		})
+	modal.SetBorder(true)
+	s.pages.AddPage("apply", modal, true, true)
+}
+
+func (s *appState) discardChanges() {
+	if s.hasOriginal {
+		_ = writeOriginalConfig(s.configPath, s.original)
+	} else {
+		_ = os.Remove(s.configPath)
+	}
+	_ = os.Remove(s.backupPath)
+	if cfg, err := configstore.Load(); err == nil && cfg != nil {
+		s.config = cfg
+	}
+	s.dirty = false
+	refreshMainMenuIfPresent(s)
+}
+
+func (s *appState) showMessage(title, message string) {
+	if s.pages.HasPage("message") {
+		return
+	}
+	modal := tview.NewModal().
+		SetText(strings.TrimSpace(message)).
+		AddButtons([]string{"OK"}).
+		SetDoneFunc(func(_ int, _ string) {
+			s.pages.RemovePage("message")
+		})
+	modal.SetTitle(title).SetBorder(true)
+	modal.SetBackgroundColor(tview.Styles.ContrastBackgroundColor)
+	modal.SetTextColor(tview.Styles.PrimaryTextColor)
+	modal.SetButtonBackgroundColor(tcell.NewRGBColor(112, 102, 255))
+	modal.SetButtonTextColor(tview.Styles.PrimaryTextColor)
+	s.pages.AddPage("message", modal, true, true)
+}
+
+func loadOriginalConfig(path string) ([]byte, bool) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, false
+		}
+		return nil, false
+	}
+	return data, true
+}
+
+func writeOriginalConfig(path string, data []byte) error {
+	return os.WriteFile(path, data, 0o600)
+}
+
+func writeBackupConfig(path string, data []byte) error {
+	return os.WriteFile(path, data, 0o600)
+}
@@ -0,0 +1,574 @@
+package ui
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func (s *appState) channelMenu() tview.Primitive {
+	items := []MenuItem{
+		{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+		channelItem(
+			"Telegram",
+			"Telegram bot settings",
+			s.config.Channels.Telegram.Enabled,
+			func() { s.push("channel-telegram", s.telegramForm()) },
+		),
+		channelItem(
+			"Discord",
+			"Discord bot settings",
+			s.config.Channels.Discord.Enabled,
+			func() { s.push("channel-discord", s.discordForm()) },
+		),
+		channelItem(
+			"QQ",
+			"QQ bot settings",
+			s.config.Channels.QQ.Enabled,
+			func() { s.push("channel-qq", s.qqForm()) },
+		),
+		channelItem(
+			"MaixCam",
+			"MaixCam gateway",
+			s.config.Channels.MaixCam.Enabled,
+			func() { s.push("channel-maixcam", s.maixcamForm()) },
+		),
+		channelItem(
+			"WhatsApp",
+			"WhatsApp bridge",
+			s.config.Channels.WhatsApp.Enabled,
+			func() { s.push("channel-whatsapp", s.whatsappForm()) },
+		),
+		channelItem(
+			"Feishu",
+			"Feishu bot settings",
+			s.config.Channels.Feishu.Enabled,
+			func() { s.push("channel-feishu", s.feishuForm()) },
+		),
+		channelItem(
+			"DingTalk",
+			"DingTalk bot settings",
+			s.config.Channels.DingTalk.Enabled,
+			func() { s.push("channel-dingtalk", s.dingtalkForm()) },
+		),
+		channelItem(
+			"Slack",
+			"Slack bot settings",
+			s.config.Channels.Slack.Enabled,
+			func() { s.push("channel-slack", s.slackForm()) },
+		),
+		channelItem(
+			"LINE",
+			"LINE bot settings",
+			s.config.Channels.LINE.Enabled,
+			func() { s.push("channel-line", s.lineForm()) },
+		),
+		channelItem(
+			"OneBot",
+			"OneBot settings",
+			s.config.Channels.OneBot.Enabled,
+			func() { s.push("channel-onebot", s.onebotForm()) },
+		),
+		channelItem(
+			"WeCom",
+			"WeCom bot settings",
+			s.config.Channels.WeCom.Enabled,
+			func() { s.push("channel-wecom", s.wecomForm()) },
+		),
+		channelItem(
+			"WeCom App",
+			"WeCom App settings",
+			s.config.Channels.WeComApp.Enabled,
+			func() { s.push("channel-wecomapp", s.wecomAppForm()) },
+		),
+	}
+
+	menu := NewMenu("Channels", items)
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+		if event.Rune() == 'q' {
+			s.pop()
+			return nil
+		}
+		return event
+	})
+	return menu
+}
+
+func refreshChannelMenuFromState(menu *Menu, s *appState) {
+	items := []MenuItem{
+		{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+		channelItem(
+			"Telegram",
+			"Telegram bot settings",
+			s.config.Channels.Telegram.Enabled,
+			func() { s.push("channel-telegram", s.telegramForm()) },
+		),
+		channelItem(
+			"Discord",
+			"Discord bot settings",
+			s.config.Channels.Discord.Enabled,
+			func() { s.push("channel-discord", s.discordForm()) },
+		),
+		channelItem(
+			"QQ",
+			"QQ bot settings",
+			s.config.Channels.QQ.Enabled,
+			func() { s.push("channel-qq", s.qqForm()) },
+		),
+		channelItem(
+			"MaixCam",
+			"MaixCam gateway",
+			s.config.Channels.MaixCam.Enabled,
+			func() { s.push("channel-maixcam", s.maixcamForm()) },
+		),
+		channelItem(
+			"WhatsApp",
+			"WhatsApp bridge",
+			s.config.Channels.WhatsApp.Enabled,
+			func() { s.push("channel-whatsapp", s.whatsappForm()) },
+		),
+		channelItem(
+			"Feishu",
+			"Feishu bot settings",
+			s.config.Channels.Feishu.Enabled,
+			func() { s.push("channel-feishu", s.feishuForm()) },
+		),
+		channelItem(
+			"DingTalk",
+			"DingTalk bot settings",
+			s.config.Channels.DingTalk.Enabled,
+			func() { s.push("channel-dingtalk", s.dingtalkForm()) },
+		),
+		channelItem(
+			"Slack",
+			"Slack bot settings",
+			s.config.Channels.Slack.Enabled,
+			func() { s.push("channel-slack", s.slackForm()) },
+		),
+		channelItem(
+			"LINE",
+			"LINE bot settings",
+			s.config.Channels.LINE.Enabled,
+			func() { s.push("channel-line", s.lineForm()) },
+		),
+		channelItem(
+			"OneBot",
+			"OneBot settings",
+			s.config.Channels.OneBot.Enabled,
+			func() { s.push("channel-onebot", s.onebotForm()) },
+		),
+		channelItem(
+			"WeCom",
+			"WeCom bot settings",
+			s.config.Channels.WeCom.Enabled,
+			func() { s.push("channel-wecom", s.wecomForm()) },
+		),
+		channelItem(
+			"WeCom App",
+			"WeCom App settings",
+			s.config.Channels.WeComApp.Enabled,
+			func() { s.push("channel-wecomapp", s.wecomAppForm()) },
+		),
+	}
+	menu.applyItems(items)
+}
+
+func (s *appState) telegramForm() tview.Primitive {
+	cfg := &s.config.Channels.Telegram
+	form := baseChannelForm("Telegram", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
+		cfg.Token = strings.TrimSpace(text)
+	})
+	form.AddInputField("Proxy", cfg.Proxy, 128, nil, func(text string) {
+		cfg.Proxy = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) discordForm() tview.Primitive {
+	cfg := &s.config.Channels.Discord
+	form := baseChannelForm("Discord", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
+		cfg.Token = strings.TrimSpace(text)
+	})
+	form.AddCheckbox("Mention Only", cfg.MentionOnly, func(checked bool) {
+		cfg.MentionOnly = checked
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) qqForm() tview.Primitive {
+	cfg := &s.config.Channels.QQ
+	form := baseChannelForm("QQ", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
+		cfg.AppID = strings.TrimSpace(text)
+	})
+	form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
+		cfg.AppSecret = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) maixcamForm() tview.Primitive {
+	cfg := &s.config.Channels.MaixCam
+	form := baseChannelForm("MaixCam", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Host", cfg.Host, 64, nil, func(text string) {
+		cfg.Host = strings.TrimSpace(text)
+	})
+	addIntField(form, "Port", cfg.Port, func(value int) { cfg.Port = value })
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) whatsappForm() tview.Primitive {
+	cfg := &s.config.Channels.WhatsApp
+	form := baseChannelForm("WhatsApp", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Bridge URL", cfg.BridgeURL, 128, nil, func(text string) {
+		cfg.BridgeURL = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) feishuForm() tview.Primitive {
+	cfg := &s.config.Channels.Feishu
+	form := baseChannelForm("Feishu", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
+		cfg.AppID = strings.TrimSpace(text)
+	})
+	form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
+		cfg.AppSecret = strings.TrimSpace(text)
+	})
+	form.AddInputField("Encrypt Key", cfg.EncryptKey, 128, nil, func(text string) {
+		cfg.EncryptKey = strings.TrimSpace(text)
+	})
+	form.AddInputField("Verification Token", cfg.VerificationToken, 128, nil, func(text string) {
+		cfg.VerificationToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) dingtalkForm() tview.Primitive {
+	cfg := &s.config.Channels.DingTalk
+	form := baseChannelForm("DingTalk", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Client ID", cfg.ClientID, 64, nil, func(text string) {
+		cfg.ClientID = strings.TrimSpace(text)
+	})
+	form.AddInputField("Client Secret", cfg.ClientSecret, 128, nil, func(text string) {
+		cfg.ClientSecret = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) slackForm() tview.Primitive {
+	cfg := &s.config.Channels.Slack
+	form := baseChannelForm("Slack", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Bot Token", cfg.BotToken, 128, nil, func(text string) {
+		cfg.BotToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("App Token", cfg.AppToken, 128, nil, func(text string) {
+		cfg.AppToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) lineForm() tview.Primitive {
+	cfg := &s.config.Channels.LINE
+	form := baseChannelForm("LINE", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Channel Secret", cfg.ChannelSecret, 128, nil, func(text string) {
+		cfg.ChannelSecret = strings.TrimSpace(text)
+	})
+	form.AddInputField("Channel Access Token", cfg.ChannelAccessToken, 128, nil, func(text string) {
+		cfg.ChannelAccessToken = strings.TrimSpace(text)
+	})
+	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
+		cfg.WebhookHost = strings.TrimSpace(text)
+	})
+	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
+	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
+		cfg.WebhookPath = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) onebotForm() tview.Primitive {
+	cfg := &s.config.Channels.OneBot
+	form := baseChannelForm("OneBot", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("WS URL", cfg.WSUrl, 128, nil, func(text string) {
+		cfg.WSUrl = strings.TrimSpace(text)
+	})
+	form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
+		cfg.AccessToken = strings.TrimSpace(text)
+	})
+	addIntField(
+		form,
+		"Reconnect Interval",
+		cfg.ReconnectInterval,
+		func(value int) { cfg.ReconnectInterval = value },
+	)
+	form.AddInputField(
+		"Group Trigger Prefix",
+		strings.Join(cfg.GroupTriggerPrefix, ","),
+		128,
+		nil,
+		func(text string) {
+			cfg.GroupTriggerPrefix = splitCSV(text)
+		},
+	)
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) wecomForm() tview.Primitive {
+	cfg := &s.config.Channels.WeCom
+	form := baseChannelForm("WeCom", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
+		cfg.Token = strings.TrimSpace(text)
+	})
+	form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
+		cfg.EncodingAESKey = strings.TrimSpace(text)
+	})
+	form.AddInputField("Webhook URL", cfg.WebhookURL, 128, nil, func(text string) {
+		cfg.WebhookURL = strings.TrimSpace(text)
+	})
+	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
+		cfg.WebhookHost = strings.TrimSpace(text)
+	})
+	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
+	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
+		cfg.WebhookPath = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	addIntField(
+		form,
+		"Reply Timeout",
+		cfg.ReplyTimeout,
+		func(value int) { cfg.ReplyTimeout = value },
+	)
+	return wrapWithBack(form, s)
+}
+
+func (s *appState) wecomAppForm() tview.Primitive {
+	cfg := &s.config.Channels.WeComApp
+	form := baseChannelForm("WeCom App", cfg.Enabled, func(v bool) {
+		cfg.Enabled = v
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["channel"]; ok {
+			refreshChannelMenuFromState(menu, s)
+		}
+	})
+	form.AddInputField("Corp ID", cfg.CorpID, 64, nil, func(text string) {
+		cfg.CorpID = strings.TrimSpace(text)
+	})
+	form.AddInputField("Corp Secret", cfg.CorpSecret, 128, nil, func(text string) {
+		cfg.CorpSecret = strings.TrimSpace(text)
+	})
+	addInt64Field(form, "Agent ID", cfg.AgentID, func(value int64) { cfg.AgentID = value })
+	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
+		cfg.Token = strings.TrimSpace(text)
+	})
+	form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
+		cfg.EncodingAESKey = strings.TrimSpace(text)
+	})
+	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
+		cfg.WebhookHost = strings.TrimSpace(text)
+	})
+	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
+	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
+		cfg.WebhookPath = strings.TrimSpace(text)
+	})
+	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
+		cfg.AllowFrom = splitCSV(text)
+	})
+	addIntField(
+		form,
+		"Reply Timeout",
+		cfg.ReplyTimeout,
+		func(value int) { cfg.ReplyTimeout = value },
+	)
+	return wrapWithBack(form, s)
+}
+
+func baseChannelForm(title string, enabled bool, onEnabled func(bool)) *tview.Form {
+	form := tview.NewForm()
+	form.SetBorder(true).SetTitle(fmt.Sprintf("Channel: %s", title))
+	form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
+	form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
+	form.AddCheckbox("Enabled", enabled, func(checked bool) {
+		onEnabled(checked)
+	})
+	return form
+}
+
+func wrapWithBack(form *tview.Form, s *appState) tview.Primitive {
+	form.AddButton("Back", func() {
+		s.pop()
+	})
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+		return event
+	})
+	return form
+}
+
+func splitCSV(input string) picoclawconfig.FlexibleStringSlice {
+	parts := strings.Split(strings.TrimSpace(input), ",")
+	cleaned := make([]string, 0, len(parts))
+	for _, part := range parts {
+		value := strings.TrimSpace(part)
+		if value == "" {
+			continue
+		}
+		cleaned = append(cleaned, value)
+	}
+	return cleaned
+}
+
+func addIntField(form *tview.Form, label string, value int, onChange func(int)) {
+	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
+		var parsed int
+		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
+			onChange(parsed)
+		}
+	})
+}
+
+func addInt64Field(form *tview.Form, label string, value int64, onChange func(int64)) {
+	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
+		var parsed int64
+		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
+			onChange(parsed)
+		}
+	})
+}
+
+func channelItem(label, description string, enabled bool, action MenuAction) MenuItem {
+	item := MenuItem{
+		Label:       label,
+		Description: description,
+		Action:      action,
+	}
+	if !enabled {
+		color := tcell.ColorGray
+		item.MainColor = &color
+	}
+	return item
+}
@@ -0,0 +1,16 @@
+//go:build !windows
+// +build !windows
+
+package ui
+
+import "os/exec"
+
+func isGatewayProcessRunning() bool {
+	cmd := exec.Command("sh", "-c", "pgrep -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
+	return cmd.Run() == nil
+}
+
+func stopGatewayProcess() error {
+	cmd := exec.Command("sh", "-c", "pkill -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
+	return cmd.Run()
+}
@@ -0,0 +1,16 @@
+//go:build windows
+// +build windows
+
+package ui
+
+import "os/exec"
+
+func isGatewayProcessRunning() bool {
+	cmd := exec.Command("tasklist", "/FI", "IMAGENAME eq picoclaw.exe")
+	return cmd.Run() == nil
+}
+
+func stopGatewayProcess() error {
+	cmd := exec.Command("taskkill", "/F", "/IM", "picoclaw.exe")
+	return cmd.Run()
+}
@@ -0,0 +1,72 @@
+package ui
+
+import (
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+type MenuAction func()
+
+type MenuItem struct {
+	Label       string
+	Description string
+	Action      MenuAction
+	Disabled    bool
+	MainColor   *tcell.Color
+	DescColor   *tcell.Color
+}
+
+type Menu struct {
+	*tview.Table
+	items []MenuItem
+}
+
+func NewMenu(title string, items []MenuItem) *Menu {
+	table := tview.NewTable().SetSelectable(true, false)
+	table.SetBorder(true).SetTitle(title)
+	table.SetBorders(false)
+	menu := &Menu{Table: table, items: items}
+	menu.applyItems(items)
+	menu.SetSelectedFunc(func(row, _ int) {
+		if row < 0 || row >= len(menu.items) {
+			return
+		}
+		item := menu.items[row]
+		if item.Disabled || item.Action == nil {
+			return
+		}
+		item.Action()
+	})
+	menu.SetSelectedStyle(
+		tcell.StyleDefault.Foreground(tview.Styles.InverseTextColor).
+			Background(tcell.NewRGBColor(189, 147, 249)),
+	)
+	return menu
+}
+
+func (m *Menu) applyItems(items []MenuItem) {
+	m.items = items
+	m.Clear()
+	for row, item := range items {
+		label := item.Label
+		if item.Disabled && label != "" {
+			label = label + " (disabled)"
+		}
+		left := tview.NewTableCell(label)
+		right := tview.NewTableCell(item.Description).SetAlign(tview.AlignRight)
+		if item.MainColor != nil {
+			left.SetTextColor(*item.MainColor)
+		}
+		if item.DescColor != nil {
+			right.SetTextColor(*item.DescColor)
+		} else {
+			right.SetTextColor(tview.Styles.TertiaryTextColor)
+		}
+		if item.Disabled {
+			left.SetTextColor(tcell.ColorGray)
+			right.SetTextColor(tcell.ColorGray)
+		}
+		m.SetCell(row, 0, left)
+		m.SetCell(row, 1, right)
+	}
+}
@@ -0,0 +1,343 @@
+package ui
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
+)
+
+func (s *appState) modelMenu() tview.Primitive {
+	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
+	items = append(items,
+		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+		MenuItem{
+			Label:       "Add model",
+			Description: "Append a new model entry",
+			Action: func() {
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
+				)
+				s.push(
+					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+					s.modelForm(len(s.config.ModelList)-1),
+				)
+			},
+		},
+	)
+	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
+	for i := range s.config.ModelList {
+		index := i
+		model := s.config.ModelList[i]
+		isValid := isModelValid(model)
+		desc := model.APIBase
+		if desc == "" {
+			desc = model.AuthMethod
+		}
+		if desc == "" {
+			desc = "api_key required"
+		}
+		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
+		if model.ModelName == currentModel && currentModel != "" {
+			label = "* " + label
+		}
+		isSelected := model.ModelName == currentModel && currentModel != ""
+		items = append(items, MenuItem{
+			Label:       label,
+			Description: desc,
+			MainColor:   modelStatusColor(isValid, isSelected),
+			Action: func() {
+				s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
+			},
+		})
+	}
+
+	menu := NewMenu("Models", items)
+	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+		if event.Rune() == 'q' {
+			s.pop()
+			return nil
+		}
+		if event.Rune() == ' ' {
+			row, _ := menu.GetSelection()
+			if row > 0 && row <= len(s.config.ModelList) {
+				model := s.config.ModelList[row-1]
+				if !isModelValid(model) {
+					s.showMessage(
+						"Invalid model",
+						"Select a model with api_key or oauth auth_method",
+					)
+					return nil
+				}
+				s.config.Agents.Defaults.Model = model.ModelName
+				s.dirty = true
+				refreshModelMenu(menu, s.config.Agents.Defaults.Model, s.config.ModelList)
+				refreshMainMenuIfPresent(s)
+			}
+			return nil
+		}
+		return event
+	})
+	return menu
+}
+
+func (s *appState) modelForm(index int) tview.Primitive {
+	model := &s.config.ModelList[index]
+	form := tview.NewForm()
+	form.SetBorder(true).SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
+	form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
+	form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
+
+	addInput(form, "Model Name", model.ModelName, func(value string) {
+		model.ModelName = value
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["model"]; ok {
+			refreshModelMenuFromState(menu, s)
+		}
+	})
+	addInput(form, "Model", model.Model, func(value string) {
+		model.Model = value
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["model"]; ok {
+			refreshModelMenuFromState(menu, s)
+		}
+	})
+	addInput(form, "API Base", model.APIBase, func(value string) {
+		model.APIBase = value
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["model"]; ok {
+			refreshModelMenuFromState(menu, s)
+		}
+	})
+	addInput(form, "API Key", model.APIKey, func(value string) {
+		model.APIKey = value
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["model"]; ok {
+			refreshModelMenuFromState(menu, s)
+		}
+	})
+	addInput(form, "Proxy", model.Proxy, func(value string) {
+		model.Proxy = value
+	})
+	addInput(form, "Auth Method", model.AuthMethod, func(value string) {
+		model.AuthMethod = value
+		s.dirty = true
+		refreshMainMenuIfPresent(s)
+		if menu, ok := s.menus["model"]; ok {
+			refreshModelMenuFromState(menu, s)
+		}
+	})
+	addInput(form, "Connect Mode", model.ConnectMode, func(value string) {
+		model.ConnectMode = value
+	})
+	addInput(form, "Workspace", model.Workspace, func(value string) {
+		model.Workspace = value
+	})
+	addInput(form, "Max Tokens Field", model.MaxTokensField, func(value string) {
+		model.MaxTokensField = value
+	})
+	addIntInput(form, "RPM", model.RPM, func(value int) {
+		model.RPM = value
+	})
+	addIntInput(form, "Request Timeout", model.RequestTimeout, func(value int) {
+		model.RequestTimeout = value
+	})
+
+	form.AddButton("Delete", func() {
+		s.deleteModel(index)
+	})
+	form.AddButton("Test", func() {
+		s.testModel(model)
+	})
+	form.AddButton("Back", func() {
+		s.pop()
+	})
+
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			s.pop()
+			return nil
+		}
+		return event
+	})
+	return form
+}
+
+func addInput(form *tview.Form, label, value string, onChange func(string)) {
+	form.AddInputField(label, value, 128, nil, func(text string) {
+		onChange(strings.TrimSpace(text))
+	})
+}
+
+func addIntInput(form *tview.Form, label string, value int, onChange func(int)) {
+	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
+		var parsed int
+		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
+			onChange(parsed)
+		}
+	})
+}
+
+func (s *appState) addModel(model picoclawconfig.ModelConfig) {
+	s.config.ModelList = append(s.config.ModelList, model)
+}
+
+func (s *appState) deleteModel(index int) {
+	if index < 0 || index >= len(s.config.ModelList) {
+		return
+	}
+	s.config.ModelList = append(s.config.ModelList[:index], s.config.ModelList[index+1:]...)
+	s.pop()
+}
+
+func modelStatusColor(valid bool, selected bool) *tcell.Color {
+	if valid {
+		color := tview.Styles.PrimaryTextColor
+		return &color
+	}
+	color := tcell.ColorGray
+	return &color
+}
+
+func refreshModelMenu(menu *Menu, currentModel string, models []picoclawconfig.ModelConfig) {
+	for i, model := range models {
+		row := i + 1
+		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
+		isValid := isModelValid(model)
+		if model.ModelName == currentModel && currentModel != "" {
+			label = "* " + label
+		}
+		cell := menu.GetCell(row, 0)
+		if cell != nil {
+			cell.SetText(label)
+			isSelected := model.ModelName == currentModel && currentModel != ""
+			color := modelStatusColor(isValid, isSelected)
+			if color != nil {
+				cell.SetTextColor(*color)
+			}
+		}
+	}
+}
+
+func refreshModelMenuFromState(menu *Menu, s *appState) {
+	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
+	items = append(items,
+		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
+		MenuItem{
+			Label:       "Add model",
+			Description: "Append a new model entry",
+			Action: func() {
+				s.addModel(
+					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
+				)
+				s.push(
+					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
+					s.modelForm(len(s.config.ModelList)-1),
+				)
+			},
+		},
+	)
+	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
+	for i := range s.config.ModelList {
+		index := i
+		model := s.config.ModelList[i]
+		isValid := isModelValid(model)
+		desc := model.APIBase
+		if desc == "" {
+			desc = model.AuthMethod
+		}
+		if desc == "" {
+			desc = "api_key required"
+		}
+		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
+		if model.ModelName == currentModel && currentModel != "" {
+			label = "* " + label
+		}
+		isSelected := model.ModelName == currentModel && currentModel != ""
+		items = append(items, MenuItem{
+			Label:       label,
+			Description: desc,
+			MainColor:   modelStatusColor(isValid, isSelected),
+			Action: func() {
+				s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
+			},
+		})
+	}
+	menu.applyItems(items)
+}
+
+func isModelValid(model picoclawconfig.ModelConfig) bool {
+	hasKey := strings.TrimSpace(model.APIKey) != "" ||
+		strings.TrimSpace(model.AuthMethod) == "oauth"
+	hasModel := strings.TrimSpace(model.Model) != ""
+	return hasKey && hasModel
+}
+
+func (s *appState) testModel(model *picoclawconfig.ModelConfig) {
+	if model == nil {
+		return
+	}
+	if strings.TrimSpace(model.APIKey) == "" {
+		s.showMessage("Missing API Key", "Set api_key before testing")
+		return
+	}
+	base := strings.TrimSpace(model.APIBase)
+	if base == "" {
+		s.showMessage("Missing API Base", "Set api_base before testing")
+		return
+	}
+	modelID := strings.TrimSpace(model.Model)
+	if modelID == "" {
+		s.showMessage("Missing Model", "Set model before testing")
+		return
+	}
+	if !strings.HasPrefix(modelID, "openai/") {
+		s.showMessage("Unsupported model", "Only openai/* models are supported for test")
+		return
+	}
+	modelName := strings.TrimPrefix(modelID, "openai/")
+	endpoint := strings.TrimRight(base, "/") + "/chat/completions"
+
+	payload := fmt.Sprintf(
+		`{"model":"%s","messages":[{"role":"user","content":"ping"}],"max_tokens":1}`,
+		modelName,
+	)
+	client := &http.Client{Timeout: 10 * time.Second}
+	request, err := http.NewRequest("POST", endpoint, strings.NewReader(payload))
+	if err != nil {
+		s.showMessage("Test failed", err.Error())
+		return
+	}
+	request.Header.Set("Content-Type", "application/json")
+	request.Header.Set("Authorization", "Bearer "+strings.TrimSpace(model.APIKey))
+
+	resp, err := client.Do(request)
+	if err != nil {
+		s.showMessage("Test failed", err.Error())
+		return
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		s.showMessage("Test OK", resp.Status)
+		return
+	}
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
+	s.showMessage(
+		"Test failed",
+		fmt.Sprintf("%s: %s", resp.Status, strings.TrimSpace(string(body))),
+	)
+}
@@ -0,0 +1,37 @@
+package ui
+
+import (
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+func applyStyles() {
+	tview.Styles.PrimitiveBackgroundColor = tcell.NewRGBColor(12, 13, 22)
+	tview.Styles.ContrastBackgroundColor = tcell.NewRGBColor(34, 19, 53)
+	tview.Styles.MoreContrastBackgroundColor = tcell.NewRGBColor(18, 18, 32)
+	tview.Styles.BorderColor = tcell.NewRGBColor(112, 102, 255)
+	tview.Styles.TitleColor = tcell.NewRGBColor(255, 121, 198)
+	tview.Styles.GraphicsColor = tcell.NewRGBColor(139, 233, 253)
+	tview.Styles.PrimaryTextColor = tcell.NewRGBColor(241, 250, 255)
+	tview.Styles.SecondaryTextColor = tcell.NewRGBColor(80, 250, 123)
+	tview.Styles.TertiaryTextColor = tcell.NewRGBColor(139, 233, 253)
+	tview.Styles.InverseTextColor = tcell.NewRGBColor(12, 13, 22)
+	tview.Styles.ContrastSecondaryTextColor = tcell.NewRGBColor(189, 147, 249)
+}
+
+func bannerView() *tview.TextView {
+	text := tview.NewTextView()
+	text.SetDynamicColors(true)
+	text.SetTextAlign(tview.AlignCenter)
+	text.SetBackgroundColor(tview.Styles.PrimitiveBackgroundColor)
+	text.SetText(
+		"[::b][#84aaff]██████╗ ██╗ ██████╗ ██████╗  ██████╗██╗      █████╗ ██╗    ██╗\n" +
+			"[#84aaff]██╔══██╗██║██╔════╝██╔═══██╗██╔════╝██║     ██╔══██╗██║    ██║\n" +
+			"[#84aaff]██████╔╝██║██║     ██║   ██║██║     ██║     ███████║██║ █╗ ██║\n" +
+			"[#84aaff]██╔═══╝ ██║██║     ██║   ██║██║     ██║     ██╔══██║██║███╗██║\n" +
+			"[#84aaff]██║     ██║╚██████╗╚██████╔╝╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
+			"[#84aaff]╚═╝     ╚═╝ ╚═════╝ ╚═════╝  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝",
+	)
+	text.SetBorder(false)
+	return text
+}
@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/ui"
+)
+
+func main() {
+	if err := ui.Run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
@@ -0,0 +1,290 @@
+# PicoClaw Launcher
+
+> [!WARNING]
+> This project is a temporary solution and will be refactored in the future to provide a complete web service. Therefore, the APIs in this directory are not stable.
+
+A standalone launcher for PicoClaw, providing visual JSON editing and OAuth provider authentication management.
+
+## Features
+
+- 📝 **Config Editor** — Sidebar-based settings UI with model management, channel configuration forms, and a raw JSON editor
+- 🤖 **Model Management** — Model card grid with availability status (grayed out without API key), primary model selection, add/edit/delete with required/optional field separation
+- 📡 **Channel Configuration** — Form-based settings for 12 channel types (Telegram, Discord, Slack, WeCom, DingTalk, Feishu, LINE, WhatsApp, QQ, OneBot, MaixCAM, etc.) with documentation links
+- 🔐 **Provider Auth** — Login to OpenAI (Device Code), Anthropic (API Token), Google Antigravity (Browser OAuth)
+- 🌐 **Embedded Frontend** — Compiles to a single binary with no external dependencies
+- 🌍 **i18n** — Chinese/English language switching with browser auto-detection
+- 🎨 **Theme** — Light / Dark / System theme toggle with localStorage persistence
+
+## Quick Start
+
+```bash
+# Build
+go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
+
+# Run with default config path (~/.picoclaw/config.json)
+./picoclaw-launcher
+
+# Specify a config file
+./picoclaw-launcher ./config.json
+
+# Allow LAN access
+./picoclaw-launcher -public
+```
+
+Open `http://localhost:18800` in your browser.
+
+## CLI Options
+
+```
+Usage: picoclaw-config [options] [config.json]
+
+Arguments:
+  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)
+
+Options:
+  -public        Listen on all interfaces (0.0.0.0), allowing access from other devices
+```
+
+## API Reference
+
+Base URL: `http://localhost:18800`
+
+---
+
+### Static Files
+
+#### GET /
+
+Serves the embedded frontend (`index.html`).
+
+---
+
+### Config API
+
+#### GET /api/config
+
+Reads the current configuration file.
+
+**Response** `200 OK`
+
+```json
+{
+  "config": { ... },
+  "path": "/Users/xiao/.picoclaw/config.json"
+}
+```
+
+---
+
+#### PUT /api/config
+
+Saves the configuration. The request body must be a complete Config JSON object.
+
+**Request Body** — `application/json`
+
+```json
+{
+  "agents": { "defaults": { "model_name": "gpt-5.2" } },
+  "model_list": [
+    {
+      "model_name": "gpt-5.2",
+      "model": "openai/gpt-5.2",
+      "auth_method": "oauth"
+    }
+  ]
+}
+```
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+**Error** `400 Bad Request` — Invalid JSON
+
+---
+
+### Auth API
+
+#### GET /api/auth/status
+
+Returns the authentication status of all providers and any in-progress device code login.
+
+**Response** `200 OK`
+
+```json
+{
+  "providers": [
+    {
+      "provider": "openai",
+      "auth_method": "oauth",
+      "status": "active",
+      "account_id": "user-xxx",
+      "expires_at": "2026-03-01T00:00:00Z"
+    }
+  ],
+  "pending_device": {
+    "provider": "openai",
+    "status": "pending",
+    "device_url": "https://auth.openai.com/activate",
+    "user_code": "ABCD-1234"
+  }
+}
+```
+
+`status` values: `active` | `expired` | `needs_refresh`
+
+`pending_device` is only present when a device code login is in progress.
+
+---
+
+#### POST /api/auth/login
+
+Initiates a provider login.
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+Supported `provider` values: `openai` | `anthropic` | `google-antigravity`
+
+##### OpenAI (Device Code Flow)
+
+Returns device code info. The server polls for completion in the background.
+
+```json
+{
+  "status": "pending",
+  "device_url": "https://auth.openai.com/activate",
+  "user_code": "ABCD-1234",
+  "message": "Open the URL and enter the code to authenticate."
+}
+```
+
+The user opens `device_url` in a browser and enters `user_code`. Once authenticated, `GET /api/auth/status` will show `pending_device.status` as `success`.
+
+##### Anthropic (API Token)
+
+Requires a `token` field in the request:
+
+```json
+{ "provider": "anthropic", "token": "sk-ant-xxx" }
+```
+
+**Response:**
+
+```json
+{ "status": "success", "message": "Anthropic token saved" }
+```
+
+##### Google Antigravity (Browser OAuth)
+
+Returns an authorization URL for the frontend to open in a new tab:
+
+```json
+{
+  "status": "redirect",
+  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
+  "message": "Open the URL to authenticate with Google."
+}
+```
+
+After authentication, Google redirects to `GET /auth/callback`, which saves the credentials and redirects back to the picoclaw-config UI.
+
+---
+
+#### POST /api/auth/logout
+
+Logs out from a provider.
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+Omit or leave `provider` empty to log out from all providers.
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+#### GET /auth/callback
+
+OAuth browser callback endpoint (used by Google Antigravity). Called by the OAuth provider's redirect — **not invoked directly by the frontend**.
+
+**Query Parameters:**
+- `state` — OAuth state for CSRF validation
+- `code` — Authorization code
+
+On success, redirects to `/#auth`.
+
+
+### Process API
+
+#### GET /api/process/status
+
+Gets the running status of the `picoclaw gateway` process.
+
+**Response** `200 OK` (Running)
+
+```json
+{
+  "process_status": "running",
+  "status": "ok",
+  "uptime": "1.010814s"
+}
+```
+
+**Response** `200 OK` (Stopped)
+
+```json
+{
+  "process_status": "stopped",
+  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
+}
+```
+
+---
+
+#### POST /api/process/start
+
+Starts the `picoclaw gateway` process in the background.
+
+**Response** `200 OK`
+
+```json
+{
+  "status": "ok",
+  "pid": 12345
+}
+```
+
+---
+
+#### POST /api/process/stop
+
+Stops the running `picoclaw gateway` process.
+
+**Response** `200 OK`
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+## Testing
+
+```bash
+go test -v ./cmd/picoclaw-launcher/
+```
@@ -0,0 +1,287 @@
+# PicoClaw Launcher
+
+> [!WARNING]
+> 该项目属于临时解决方案，后续会重构并提供完整的 Web 服务，因此该目录下的接口并不稳定。
+
+PicoClaw 的独立启动器，提供可视化 JSON 配置编辑和 OAuth Provider 认证管理。
+
+## 功能
+
+- 📝 **配置编辑** — 侧边栏式设置 UI，支持模型管理、通道配置表单和原始 JSON 编辑器
+- 🤖 **模型管理** — 模型卡片网格，可用性状态显示（无 API Key 时灰色），主模型选择，增删改查，必填/选填字段分离
+- 📡 **通道配置** — 12 种通道类型（Telegram、Discord、Slack、企业微信、钉钉、飞书、LINE、WhatsApp、QQ、OneBot、MaixCAM 等）的表单化配置，附带文档链接
+- 🔐 **Provider 认证** — 支持 OpenAI (Device Code)、Anthropic (API Token)、Google Antigravity (Browser OAuth) 登录
+- 🌐 **嵌入式前端** — 编译为单一二进制文件，无需额外依赖
+- 🌍 **国际化** — 中英文切换，首次访问自动检测浏览器语言
+- 🎨 **主题** — 亮色 / 暗色 / 跟随系统，偏好保存在 localStorage
+
+## 快速开始
+
+```bash
+# 编译
+go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
+
+# 运行（使用默认配置路径 ~/.picoclaw/config.json）
+./picoclaw-launcher
+
+# 指定配置文件
+./picoclaw-launcher ./config.json
+
+# 允许局域网访问
+./picoclaw-launcher -public
+```
+
+启动后在浏览器中打开 `http://localhost:18800`。
+
+## 命令行参数
+
+```
+Usage: picoclaw-launcher [options] [config.json]
+
+Arguments:
+  config.json    配置文件路径（默认: ~/.picoclaw/config.json）
+
+Options:
+  -public        监听所有网络接口（0.0.0.0），允许局域网设备访问
+```
+
+## API 文档
+
+Base URL: `http://localhost:18800`
+
+### 静态文件
+
+#### GET /
+
+提供嵌入式前端页面（`index.html`）。
+
+---
+
+### Config API
+
+#### GET /api/config
+
+读取当前配置文件内容。
+
+**Response** `200 OK`
+
+```json
+{
+  "config": { ... },
+  "path": "/Users/xiao/.picoclaw/config.json"
+}
+```
+
+---
+
+#### PUT /api/config
+
+保存配置。请求体为完整的 Config JSON。
+
+**Request Body** — `application/json`
+
+```json
+{
+  "agents": { "defaults": { "model_name": "gpt-5.2" } },
+  "model_list": [
+    {
+      "model_name": "gpt-5.2",
+      "model": "openai/gpt-5.2",
+      "auth_method": "oauth"
+    }
+  ]
+}
+```
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+**Error** `400 Bad Request` — 无效 JSON
+
+---
+
+### Auth API
+
+#### GET /api/auth/status
+
+获取所有 Provider 的认证状态和进行中的 Device Code 登录信息。
+
+**Response** `200 OK`
+
+```json
+{
+  "providers": [
+    {
+      "provider": "openai",
+      "auth_method": "oauth",
+      "status": "active",
+      "account_id": "user-xxx",
+      "expires_at": "2026-03-01T00:00:00Z"
+    }
+  ],
+  "pending_device": {
+    "provider": "openai",
+    "status": "pending",
+    "device_url": "https://auth.openai.com/activate",
+    "user_code": "ABCD-1234"
+  }
+}
+```
+
+`status` 可选值: `active` | `expired` | `needs_refresh`
+
+`pending_device` 仅在有进行中的 Device Code 登录时返回。
+
+---
+
+#### POST /api/auth/login
+
+发起 Provider 登录。
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+支持的 `provider` 值: `openai` | `anthropic` | `google-antigravity`
+
+##### OpenAI (Device Code Flow)
+
+返回 Device Code 信息，后台自动轮询认证结果：
+
+```json
+{
+  "status": "pending",
+  "device_url": "https://auth.openai.com/activate",
+  "user_code": "ABCD-1234",
+  "message": "Open the URL and enter the code to authenticate."
+}
+```
+
+用户在浏览器中打开 `device_url` 并输入 `user_code`。认证完成后通过 `GET /api/auth/status` 的 `pending_device.status` 变为 `success` 通知前端。
+
+##### Anthropic (API Token)
+
+需在请求中附带 token：
+
+```json
+{ "provider": "anthropic", "token": "sk-ant-xxx" }
+```
+
+**Response:**
+
+```json
+{ "status": "success", "message": "Anthropic token saved" }
+```
+
+##### Google Antigravity (Browser OAuth)
+
+返回授权 URL，前端打开新标签页：
+
+```json
+{
+  "status": "redirect",
+  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
+  "message": "Open the URL to authenticate with Google."
+}
+```
+
+认证完成后 Google 回调至 `GET /auth/callback`，自动保存凭据并重定向回 picoclaw-config 页面。
+
+---
+
+#### POST /api/auth/logout
+
+登出 Provider。
+
+**Request Body** — `application/json`
+
+```json
+{ "provider": "openai" }
+```
+
+传空字符串或省略 `provider` 则登出所有 Provider。
+
+**Response** `200 OK`
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+#### GET /auth/callback
+
+OAuth Browser 回调端点（Google Antigravity 专用），由 OAuth Provider 重定向调用，**非前端直接使用**。
+
+**Query Parameters:**
+- `state` — OAuth state 校验
+- `code` — 授权码
+
+认证成功后重定向到 `/#auth`。
+
+### Process API
+
+#### GET /api/process/status
+
+获取 `picoclaw gateway` 进程的运行状态。
+
+**Response** `200 OK` (运行中)
+
+```json
+{
+  "process_status": "running",
+  "status": "ok",
+  "uptime": "1.010814s"
+}
+```
+
+**Response** `200 OK` (未运行)
+
+```json
+{
+  "process_status": "stopped",
+  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
+}
+```
+
+---
+
+#### POST /api/process/start
+
+在后台启动 `picoclaw gateway` 进程。
+
+**Response** `200 OK`
+
+```json
+{
+  "status": "ok",
+  "pid": 12345
+}
+```
+
+---
+
+#### POST /api/process/stop
+
+停止正在运行的 `picoclaw gateway` 进程。
+
+**Response** `200 OK`
+
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+## 测试
+
+```bash
+go test -v ./cmd/picoclaw-launcher/
+```
@@ -0,0 +1,147 @@
+package server
+
+import (
+	"log"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// updateConfigAfterLogin updates config.json after a successful provider login.
+func updateConfigAfterLogin(configPath, provider string, cred *auth.AuthCredential) {
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		log.Printf("Warning: could not load config to update auth_method: %v", err)
+		return
+	}
+
+	switch provider {
+	case "openai":
+		cfg.Providers.OpenAI.AuthMethod = "oauth"
+		found := false
+		for i := range cfg.ModelList {
+			if isOpenAIModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = "oauth"
+				found = true
+				break
+			}
+		}
+		if !found {
+			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+				ModelName:  "gpt-5.2",
+				Model:      "openai/gpt-5.2",
+				AuthMethod: "oauth",
+			})
+		}
+		cfg.Agents.Defaults.ModelName = "gpt-5.2"
+
+	case "anthropic":
+		cfg.Providers.Anthropic.AuthMethod = "token"
+		found := false
+		for i := range cfg.ModelList {
+			if isAnthropicModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = "token"
+				found = true
+				break
+			}
+		}
+		if !found {
+			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+				ModelName:  "claude-sonnet-4.6",
+				Model:      "anthropic/claude-sonnet-4.6",
+				AuthMethod: "token",
+			})
+		}
+		cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
+
+	case "google-antigravity":
+		cfg.Providers.Antigravity.AuthMethod = "oauth"
+		found := false
+		for i := range cfg.ModelList {
+			if isAntigravityModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = "oauth"
+				found = true
+				break
+			}
+		}
+		if !found {
+			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+				ModelName:  "gemini-flash",
+				Model:      "antigravity/gemini-3-flash",
+				AuthMethod: "oauth",
+			})
+		}
+		cfg.Agents.Defaults.ModelName = "gemini-flash"
+	}
+
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		log.Printf("Warning: could not update config: %v", err)
+	}
+}
+
+// clearAuthMethodInConfig clears auth_method for a specific provider in config.json.
+func clearAuthMethodInConfig(configPath, provider string) {
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return
+	}
+
+	for i := range cfg.ModelList {
+		switch provider {
+		case "openai":
+			if isOpenAIModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = ""
+			}
+		case "anthropic":
+			if isAnthropicModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = ""
+			}
+		case "google-antigravity", "antigravity":
+			if isAntigravityModel(cfg.ModelList[i].Model) {
+				cfg.ModelList[i].AuthMethod = ""
+			}
+		}
+	}
+
+	switch provider {
+	case "openai":
+		cfg.Providers.OpenAI.AuthMethod = ""
+	case "anthropic":
+		cfg.Providers.Anthropic.AuthMethod = ""
+	case "google-antigravity", "antigravity":
+		cfg.Providers.Antigravity.AuthMethod = ""
+	}
+
+	config.SaveConfig(configPath, cfg)
+}
+
+// clearAllAuthMethodsInConfig clears auth_method for all providers in config.json.
+func clearAllAuthMethodsInConfig(configPath string) {
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return
+	}
+	for i := range cfg.ModelList {
+		cfg.ModelList[i].AuthMethod = ""
+	}
+	cfg.Providers.OpenAI.AuthMethod = ""
+	cfg.Providers.Anthropic.AuthMethod = ""
+	cfg.Providers.Antigravity.AuthMethod = ""
+	config.SaveConfig(configPath, cfg)
+}
+
+// ── Model identification helpers ─────────────────────────────────
+
+func isOpenAIModel(model string) bool {
+	return model == "openai" || strings.HasPrefix(model, "openai/")
+}
+
+func isAnthropicModel(model string) bool {
+	return model == "anthropic" || strings.HasPrefix(model, "anthropic/")
+}
+
+func isAntigravityModel(model string) bool {
+	return model == "antigravity" || model == "google-antigravity" ||
+		strings.HasPrefix(model, "antigravity/") || strings.HasPrefix(model, "google-antigravity/")
+}
@@ -0,0 +1,222 @@
+package server
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ── Model identification helpers ─────────────────────────────────
+
+func TestIsOpenAIModel(t *testing.T) {
+	tests := []struct {
+		model string
+		want  bool
+	}{
+		{"openai", true},
+		{"openai/gpt-4o", true},
+		{"openai/gpt-5.2", true},
+		{"anthropic", false},
+		{"anthropic/claude-sonnet-4.6", false},
+		{"openai-compatible", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		if got := isOpenAIModel(tt.model); got != tt.want {
+			t.Errorf("isOpenAIModel(%q) = %v, want %v", tt.model, got, tt.want)
+		}
+	}
+}
+
+func TestIsAnthropicModel(t *testing.T) {
+	tests := []struct {
+		model string
+		want  bool
+	}{
+		{"anthropic", true},
+		{"anthropic/claude-sonnet-4.6", true},
+		{"openai", false},
+		{"openai/gpt-4o", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		if got := isAnthropicModel(tt.model); got != tt.want {
+			t.Errorf("isAnthropicModel(%q) = %v, want %v", tt.model, got, tt.want)
+		}
+	}
+}
+
+func TestIsAntigravityModel(t *testing.T) {
+	tests := []struct {
+		model string
+		want  bool
+	}{
+		{"antigravity", true},
+		{"google-antigravity", true},
+		{"antigravity/gemini-3-flash", true},
+		{"google-antigravity/gemini-3-flash", true},
+		{"openai", false},
+		{"antigravity-custom", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		if got := isAntigravityModel(tt.model); got != tt.want {
+			t.Errorf("isAntigravityModel(%q) = %v, want %v", tt.model, got, tt.want)
+		}
+	}
+}
+
+// ── Config update helpers ────────────────────────────────────────
+
+func writeTempConfigViaSave(t *testing.T, cfg *config.Config) string {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.json")
+	if err := config.SaveConfig(path, cfg); err != nil {
+		t.Fatalf("save config: %v", err)
+	}
+	return path
+}
+
+func loadTempConfig(t *testing.T, path string) *config.Config {
+	t.Helper()
+	cfg, err := config.LoadConfig(path)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	return cfg
+}
+
+func TestUpdateConfigAfterLogin_OpenAI_ExistingModel(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
+		},
+	}
+	path := writeTempConfigViaSave(t, cfg)
+
+	cred := &auth.AuthCredential{AuthMethod: "oauth"}
+	updateConfigAfterLogin(path, "openai", cred)
+
+	result := loadTempConfig(t, path)
+
+	// Model-level auth_method persists through serialization
+	if len(result.ModelList) != 1 {
+		t.Fatalf("expected 1 model, got %d", len(result.ModelList))
+	}
+	if result.ModelList[0].AuthMethod != "oauth" {
+		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
+	}
+}
+
+func TestUpdateConfigAfterLogin_OpenAI_NoExistingModel(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6"},
+		},
+	}
+	path := writeTempConfigViaSave(t, cfg)
+
+	cred := &auth.AuthCredential{AuthMethod: "oauth"}
+	updateConfigAfterLogin(path, "openai", cred)
+
+	result := loadTempConfig(t, path)
+
+	if len(result.ModelList) != 2 {
+		t.Fatalf("expected 2 models (original + added), got %d", len(result.ModelList))
+	}
+	if result.ModelList[1].Model != "openai/gpt-5.2" {
+		t.Errorf("expected added model openai/gpt-5.2, got %q", result.ModelList[1].Model)
+	}
+	if result.Agents.Defaults.ModelName != "gpt-5.2" {
+		t.Errorf("expected default model_name=gpt-5.2, got %q", result.Agents.Defaults.ModelName)
+	}
+}
+
+func TestUpdateConfigAfterLogin_Anthropic(t *testing.T) {
+	cfg := &config.Config{}
+	path := writeTempConfigViaSave(t, cfg)
+
+	cred := &auth.AuthCredential{AuthMethod: "token"}
+	updateConfigAfterLogin(path, "anthropic", cred)
+
+	result := loadTempConfig(t, path)
+
+	// Model should be added with correct auth_method
+	if len(result.ModelList) != 1 {
+		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
+	}
+	if result.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
+		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", result.ModelList[0].Model)
+	}
+	if result.ModelList[0].AuthMethod != "token" {
+		t.Errorf("expected model auth_method=token, got %q", result.ModelList[0].AuthMethod)
+	}
+}
+
+func TestUpdateConfigAfterLogin_GoogleAntigravity(t *testing.T) {
+	cfg := &config.Config{}
+	path := writeTempConfigViaSave(t, cfg)
+
+	cred := &auth.AuthCredential{AuthMethod: "oauth"}
+	updateConfigAfterLogin(path, "google-antigravity", cred)
+
+	result := loadTempConfig(t, path)
+
+	// Model should be added with correct auth_method
+	if len(result.ModelList) != 1 {
+		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
+	}
+	if result.ModelList[0].Model != "antigravity/gemini-3-flash" {
+		t.Errorf("expected model antigravity/gemini-3-flash, got %q", result.ModelList[0].Model)
+	}
+	if result.ModelList[0].AuthMethod != "oauth" {
+		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
+	}
+}
+
+func TestClearAuthMethodInConfig(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
+			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+		},
+	}
+	path := writeTempConfigViaSave(t, cfg)
+
+	clearAuthMethodInConfig(path, "openai")
+
+	result := loadTempConfig(t, path)
+
+	// Openai model auth_method should be cleared
+	if result.ModelList[0].AuthMethod != "" {
+		t.Errorf("expected openai model auth_method cleared, got %q", result.ModelList[0].AuthMethod)
+	}
+	// Anthropic model should be unchanged
+	if result.ModelList[1].AuthMethod != "token" {
+		t.Errorf("expected anthropic model auth_method unchanged, got %q", result.ModelList[1].AuthMethod)
+	}
+}
+
+func TestClearAllAuthMethodsInConfig(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
+			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+			{ModelName: "gemini", Model: "antigravity/gemini-3-flash", AuthMethod: "oauth"},
+		},
+	}
+	path := writeTempConfigViaSave(t, cfg)
+
+	clearAllAuthMethodsInConfig(path)
+
+	result := loadTempConfig(t, path)
+
+	for i, m := range result.ModelList {
+		if m.AuthMethod != "" {
+			t.Errorf("model[%d] auth_method not cleared, got %q", i, m.AuthMethod)
+		}
+	}
+}
@@ -0,0 +1,312 @@
+package server
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// oauthSession stores in-flight OAuth state for browser-based flows.
+type oauthSession struct {
+	Provider    string
+	PKCE        auth.PKCECodes
+	State       string
+	RedirectURI string
+	OAuthCfg    auth.OAuthProviderConfig
+	ConfigPath  string
+}
+
+// deviceCodeSession stores in-flight device code flow state.
+type deviceCodeSession struct {
+	mu         sync.Mutex
+	Provider   string
+	Info       *auth.DeviceCodeInfo
+	OAuthCfg   auth.OAuthProviderConfig
+	ConfigPath string
+	Status     string // "pending", "success", "error"
+	Error      string
+	Done       bool
+}
+
+var (
+	oauthSessions   = map[string]*oauthSession{} // keyed by state
+	oauthSessionsMu sync.Mutex
+
+	activeDeviceSession   *deviceCodeSession
+	activeDeviceSessionMu sync.Mutex
+)
+
+// handleOpenAILogin starts the OpenAI device code flow and returns device code info to the frontend.
+func handleOpenAILogin(w http.ResponseWriter, configPath string) {
+	// Check if there's already a pending device code session
+	activeDeviceSessionMu.Lock()
+	if activeDeviceSession != nil {
+		activeDeviceSession.mu.Lock()
+		if !activeDeviceSession.Done {
+			resp := map[string]any{
+				"status":     "pending",
+				"device_url": activeDeviceSession.Info.VerifyURL,
+				"user_code":  activeDeviceSession.Info.UserCode,
+				"message":    "Device code flow already in progress. Enter the code in your browser.",
+			}
+			activeDeviceSession.mu.Unlock()
+			activeDeviceSessionMu.Unlock()
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(resp)
+			return
+		}
+		activeDeviceSession.mu.Unlock()
+	}
+	activeDeviceSessionMu.Unlock()
+
+	// Request a device code
+	oauthCfg := auth.OpenAIOAuthConfig()
+	info, err := auth.RequestDeviceCode(oauthCfg)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to request device code: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	session := &deviceCodeSession{
+		Provider:   "openai",
+		Info:       info,
+		OAuthCfg:   oauthCfg,
+		ConfigPath: configPath,
+		Status:     "pending",
+	}
+
+	activeDeviceSessionMu.Lock()
+	activeDeviceSession = session
+	activeDeviceSessionMu.Unlock()
+
+	// Start background polling
+	go func() {
+		deadline := time.After(15 * time.Minute)
+		ticker := time.NewTicker(time.Duration(info.Interval) * time.Second)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-deadline:
+				session.mu.Lock()
+				session.Status = "error"
+				session.Error = "Authentication timed out after 15 minutes"
+				session.Done = true
+				session.mu.Unlock()
+				return
+			case <-ticker.C:
+				cred, err := auth.PollDeviceCodeOnce(oauthCfg, info.DeviceAuthID, info.UserCode)
+				if err != nil {
+					continue // Still pending
+				}
+				if cred != nil {
+					if saveErr := auth.SetCredential("openai", cred); saveErr != nil {
+						session.mu.Lock()
+						session.Status = "error"
+						session.Error = saveErr.Error()
+						session.Done = true
+						session.mu.Unlock()
+						return
+					}
+					updateConfigAfterLogin(configPath, "openai", cred)
+					session.mu.Lock()
+					session.Status = "success"
+					session.Done = true
+					session.mu.Unlock()
+					log.Printf("OpenAI device code login successful (account: %s)", cred.AccountID)
+					return
+				}
+			}
+		}
+	}()
+
+	// Return device code info to frontend
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status":     "pending",
+		"device_url": info.VerifyURL,
+		"user_code":  info.UserCode,
+		"message":    "Open the URL and enter the code to authenticate.",
+	})
+}
+
+// handleAnthropicLogin saves a pasted API token for Anthropic.
+func handleAnthropicLogin(w http.ResponseWriter, token, configPath string) {
+	if token == "" {
+		http.Error(w, "Token is required for Anthropic login", http.StatusBadRequest)
+		return
+	}
+
+	cred := &auth.AuthCredential{
+		AccessToken: token,
+		Provider:    "anthropic",
+		AuthMethod:  "token",
+	}
+
+	if err := auth.SetCredential("anthropic", cred); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save credentials: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	updateConfigAfterLogin(configPath, "anthropic", cred)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":  "success",
+		"message": "Anthropic token saved",
+	})
+}
+
+// handleGoogleAntigravityLogin generates a PKCE + auth URL and returns it to the frontend.
+func handleGoogleAntigravityLogin(w http.ResponseWriter, r *http.Request, configPath string) {
+	oauthCfg := auth.GoogleAntigravityOAuthConfig()
+
+	pkce, err := auth.GeneratePKCE()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to generate PKCE: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	state, err := auth.GenerateState()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to generate state: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	// Build redirect URI pointing to picoclaw-launcher's own callback
+	scheme := "http"
+	redirectURI := fmt.Sprintf("%s://%s/auth/callback", scheme, r.Host)
+
+	authURL := auth.BuildAuthorizeURL(oauthCfg, pkce, state, redirectURI)
+
+	// Store session for callback
+	oauthSessionsMu.Lock()
+	oauthSessions[state] = &oauthSession{
+		Provider:    "google-antigravity",
+		PKCE:        pkce,
+		State:       state,
+		RedirectURI: redirectURI,
+		OAuthCfg:    oauthCfg,
+		ConfigPath:  configPath,
+	}
+	oauthSessionsMu.Unlock()
+
+	// Clean up stale sessions after 10 minutes
+	go func() {
+		time.Sleep(10 * time.Minute)
+		oauthSessionsMu.Lock()
+		delete(oauthSessions, state)
+		oauthSessionsMu.Unlock()
+	}()
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":   "redirect",
+		"auth_url": authURL,
+		"message":  "Open the URL to authenticate with Google.",
+	})
+}
+
+// handleOAuthCallback processes the OAuth callback from Google Antigravity.
+func handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
+	state := r.URL.Query().Get("state")
+	code := r.URL.Query().Get("code")
+
+	oauthSessionsMu.Lock()
+	session, ok := oauthSessions[state]
+	if ok {
+		delete(oauthSessions, state)
+	}
+	oauthSessionsMu.Unlock()
+
+	if !ok {
+		http.Error(w, "Invalid or expired OAuth state", http.StatusBadRequest)
+		return
+	}
+
+	if code == "" {
+		errMsg := r.URL.Query().Get("error")
+		w.Header().Set("Content-Type", "text/html")
+		fmt.Fprintf(
+			w,
+			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
+			errMsg,
+		)
+		return
+	}
+
+	cred, err := auth.ExchangeCodeForTokens(session.OAuthCfg, code, session.PKCE.CodeVerifier, session.RedirectURI)
+	if err != nil {
+		w.Header().Set("Content-Type", "text/html")
+		fmt.Fprintf(
+			w,
+			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
+			err.Error(),
+		)
+		return
+	}
+
+	cred.Provider = session.Provider
+
+	// Fetch user info for Google Antigravity
+	if session.Provider == "google-antigravity" {
+		if email, err := fetchGoogleUserEmail(cred.AccessToken); err == nil {
+			cred.Email = email
+		}
+		if projectID, err := providers.FetchAntigravityProjectID(cred.AccessToken); err == nil {
+			cred.ProjectID = projectID
+		}
+	}
+
+	if err := auth.SetCredential(session.Provider, cred); err != nil {
+		w.Header().Set("Content-Type", "text/html")
+		fmt.Fprintf(w, `<html><body><h2>Failed to save credentials</h2><p>%s</p></body></html>`, err.Error())
+		return
+	}
+
+	updateConfigAfterLogin(session.ConfigPath, session.Provider, cred)
+
+	// Redirect back to picoclaw-launcher UI
+	w.Header().Set("Content-Type", "text/html")
+	fmt.Fprintf(w, `<html><body>
+		<h2>Authentication successful!</h2>
+		<p>Redirecting back to Config Editor...</p>
+		<script>setTimeout(function(){ window.location.href = '/#auth'; }, 1000);</script>
+	</body></html>`)
+}
+
+// fetchGoogleUserEmail retrieves the user's email from Google's userinfo endpoint.
+func fetchGoogleUserEmail(accessToken string) (string, error) {
+	req, err := http.NewRequest("GET", "https://www.googleapis.com/oauth2/v2/userinfo", nil)
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("userinfo request failed: %s", string(body))
+	}
+
+	var userInfo struct {
+		Email string `json:"email"`
+	}
+	if err := json.Unmarshal(body, &userInfo); err != nil {
+		return "", err
+	}
+	return userInfo.Email, nil
+}
@@ -0,0 +1,99 @@
+package server
+
+import "sync"
+
+// LogBuffer is a thread-safe ring buffer that stores the most recent N log lines.
+// It supports incremental reads via LinesSince and tracks a runID that increments
+// on each Reset (used to detect gateway restarts).
+type LogBuffer struct {
+	mu    sync.RWMutex
+	lines []string
+	cap   int
+	total int // total lines ever appended in current run
+	runID int
+}
+
+// NewLogBuffer creates a LogBuffer with the given capacity.
+func NewLogBuffer(capacity int) *LogBuffer {
+	return &LogBuffer{
+		lines: make([]string, 0, capacity),
+		cap:   capacity,
+	}
+}
+
+// Append adds a line to the buffer. If the buffer is full, the oldest line is evicted.
+func (b *LogBuffer) Append(line string) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if len(b.lines) < b.cap {
+		b.lines = append(b.lines, line)
+	} else {
+		b.lines[b.total%b.cap] = line
+	}
+
+	b.total++
+}
+
+// Reset clears the buffer and increments the runID. Call this when starting a new gateway process.
+func (b *LogBuffer) Reset() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.lines = b.lines[:0]
+	b.total = 0
+	b.runID++
+}
+
+// LinesSince returns lines appended after the given offset, the current total count, and the runID.
+// If offset >= total, no lines are returned. If offset is too old (evicted), all buffered lines are returned.
+func (b *LogBuffer) LinesSince(offset int) (lines []string, total int, runID int) {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	total = b.total
+	runID = b.runID
+
+	if offset >= b.total {
+		return nil, total, runID
+	}
+
+	buffered := len(b.lines)
+
+	// How many new lines since offset
+	newCount := b.total - offset
+	if newCount > buffered {
+		newCount = buffered
+	}
+
+	result := make([]string, newCount)
+
+	if b.total <= b.cap {
+		// Buffer hasn't wrapped yet — simple slice
+		copy(result, b.lines[buffered-newCount:])
+	} else {
+		// Buffer has wrapped — read from ring
+		start := (b.total - newCount) % b.cap
+		for i := range newCount {
+			result[i] = b.lines[(start+i)%b.cap]
+		}
+	}
+
+	return result, total, runID
+}
+
+// RunID returns the current run identifier.
+func (b *LogBuffer) RunID() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	return b.runID
+}
+
+// Total returns the total number of lines appended in the current run.
+func (b *LogBuffer) Total() int {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	return b.total
+}
@@ -0,0 +1,116 @@
+package server
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestLogBuffer_Basic(t *testing.T) {
+	buf := NewLogBuffer(5)
+
+	// Empty buffer
+	lines, total, runID := buf.LinesSince(0)
+	assert.Nil(t, lines)
+	assert.Equal(t, 0, total)
+	assert.Equal(t, 0, runID)
+
+	// Append some lines
+	buf.Append("line1")
+	buf.Append("line2")
+	buf.Append("line3")
+
+	lines, total, runID = buf.LinesSince(0)
+	assert.Equal(t, []string{"line1", "line2", "line3"}, lines)
+	assert.Equal(t, 3, total)
+	assert.Equal(t, 0, runID)
+
+	// Incremental read
+	lines, total, _ = buf.LinesSince(2)
+	assert.Equal(t, []string{"line3"}, lines)
+	assert.Equal(t, 3, total)
+
+	// No new lines
+	lines, total, _ = buf.LinesSince(3)
+	assert.Nil(t, lines)
+	assert.Equal(t, 3, total)
+}
+
+func TestLogBuffer_Wrap(t *testing.T) {
+	buf := NewLogBuffer(3)
+
+	buf.Append("a")
+	buf.Append("b")
+	buf.Append("c")
+	buf.Append("d") // evicts "a"
+	buf.Append("e") // evicts "b"
+
+	lines, total, _ := buf.LinesSince(0)
+	assert.Equal(t, []string{"c", "d", "e"}, lines)
+	assert.Equal(t, 5, total)
+
+	// Incremental after wrap
+	lines, total, _ = buf.LinesSince(3)
+	assert.Equal(t, []string{"d", "e"}, lines)
+	assert.Equal(t, 5, total)
+
+	// Offset too old (before buffer start), get all buffered
+	lines, total, _ = buf.LinesSince(1)
+	assert.Equal(t, []string{"c", "d", "e"}, lines)
+	assert.Equal(t, 5, total)
+}
+
+func TestLogBuffer_Reset(t *testing.T) {
+	buf := NewLogBuffer(5)
+
+	buf.Append("before")
+	assert.Equal(t, 0, buf.RunID())
+
+	buf.Reset()
+	assert.Equal(t, 1, buf.RunID())
+	assert.Equal(t, 0, buf.Total())
+
+	lines, total, runID := buf.LinesSince(0)
+	assert.Nil(t, lines)
+	assert.Equal(t, 0, total)
+	assert.Equal(t, 1, runID)
+
+	buf.Append("after")
+	lines, total, runID = buf.LinesSince(0)
+	assert.Equal(t, []string{"after"}, lines)
+	assert.Equal(t, 1, total)
+	assert.Equal(t, 1, runID)
+}
+
+func TestLogBuffer_Concurrent(t *testing.T) {
+	buf := NewLogBuffer(100)
+	var wg sync.WaitGroup
+
+	// 10 writers
+	for i := range 10 {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := range 50 {
+				buf.Append(fmt.Sprintf("writer-%d-line-%d", id, j))
+			}
+		}(i)
+	}
+
+	// 5 readers
+	for range 5 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for range 100 {
+				buf.LinesSince(0)
+			}
+		}()
+	}
+
+	wg.Wait()
+
+	assert.Equal(t, 500, buf.Total())
+}
@@ -0,0 +1,232 @@
+package server
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// gatewayLogs stores captured stdout/stderr from the gateway process launched by the launcher.
+var gatewayLogs = NewLogBuffer(200)
+
+// RegisterProcessAPI registers endpoints to start, stop and check status of the picoclaw gateway.
+func RegisterProcessAPI(mux *http.ServeMux, absPath string) {
+	mux.HandleFunc("GET /api/process/status", func(w http.ResponseWriter, r *http.Request) {
+		handleStatusGateway(w, r, absPath)
+	})
+	mux.HandleFunc("POST /api/process/start", handleStartGateway)
+	mux.HandleFunc("POST /api/process/stop", handleStopGateway)
+}
+
+func handleStartGateway(w http.ResponseWriter, r *http.Request) {
+	// Locate picoclaw executable:
+	// 1. Try same directory as current executable
+	// 2. Fallback to just "picoclaw" (relies on $PATH)
+	execPath := "picoclaw"
+
+	if exe, err := os.Executable(); err == nil {
+		dir := filepath.Dir(exe)
+		candidate := filepath.Join(dir, "picoclaw")
+		if runtime.GOOS == "windows" {
+			candidate += ".exe"
+		}
+
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			execPath = candidate
+		}
+	}
+
+	cmd := exec.Command(execPath, "gateway")
+
+	stdoutPipe, err := cmd.StdoutPipe()
+	if err != nil {
+		log.Printf("Failed to create stdout pipe: %v\n", err)
+		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	stderrPipe, err := cmd.StderrPipe()
+	if err != nil {
+		log.Printf("Failed to create stderr pipe: %v\n", err)
+		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	// Clear old logs and increment runID before starting
+	gatewayLogs.Reset()
+
+	if err := cmd.Start(); err != nil {
+		log.Printf("Failed to start picoclaw gateway: %v\n", err)
+		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	// Read stdout and stderr into the log buffer
+	go scanPipe(stdoutPipe, gatewayLogs)
+	go scanPipe(stderrPipe, gatewayLogs)
+
+	// Wait for the process to exit in the background to avoid zombies
+	go func() {
+		if err := cmd.Wait(); err != nil {
+			log.Printf("Gateway process exited: %v\n", err)
+		}
+	}()
+
+	log.Printf("Started picoclaw gateway (PID: %d) from %s\n", cmd.Process.Pid, execPath)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    cmd.Process.Pid,
+	})
+}
+
+// scanPipe reads lines from r and appends them to buf. It returns when r reaches EOF.
+func scanPipe(r io.Reader, buf *LogBuffer) {
+	scanner := bufio.NewScanner(r)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) // up to 1MB per line
+
+	for scanner.Scan() {
+		buf.Append(scanner.Text())
+	}
+}
+
+func handleStopGateway(w http.ResponseWriter, r *http.Request) {
+	var err error
+	if runtime.GOOS == "windows" {
+		// Kill via taskkill finding picoclaw.exe (though it might kill this config tool if it's named picoclaw-launcher.exe...? No, /IM does exact match usually, but just to be safe let's stop exactly picoclaw.exe)
+		// Alternatively, we use powershell to kill processes with commandline containing 'gateway'
+		psCmd := `Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -match 'picoclaw.*gateway' } | ForEach-Object { Stop-Process $_.ProcessId -Force }`
+		err = exec.Command("powershell", "-Command", psCmd).Run()
+	} else {
+		// Linux/macOS
+		err = exec.Command("pkill", "-f", "picoclaw gateway").Run()
+	}
+
+	if err != nil {
+		log.Printf("Warning: Failed to stop gateway (perhaps not running?): %v\n", err)
+		// We still return 200 OK because pkill returns an error if no process was found
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "ok", // or "not_found"
+			"msg":    "Stop command executed, but returned error (process might not be running).",
+			"error":  err.Error(),
+		})
+		return
+	}
+
+	log.Printf("Stopped picoclaw gateway processes.\n")
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status": "ok",
+	})
+}
+
+func handleStatusGateway(w http.ResponseWriter, r *http.Request, absPath string) {
+	cfg, cfgErr := config.LoadConfig(absPath)
+	host := "127.0.0.1"
+	port := 18790
+	if cfgErr == nil && cfg != nil {
+		if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
+			host = cfg.Gateway.Host
+		}
+		if cfg.Gateway.Port != 0 {
+			port = cfg.Gateway.Port
+		}
+	}
+
+	url := fmt.Sprintf("http://%s/health", net.JoinHostPort(host, strconv.Itoa(port)))
+	client := http.Client{Timeout: 2 * time.Second}
+	resp, err := client.Get(url)
+
+	// Build the response data map
+	data := map[string]any{}
+
+	if err != nil {
+		data["process_status"] = "stopped"
+		data["error"] = err.Error()
+	} else {
+		defer resp.Body.Close()
+
+		if resp.StatusCode != http.StatusOK {
+			data["process_status"] = "error"
+			data["status_code"] = resp.StatusCode
+		} else {
+			var healthData map[string]any
+			if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
+				data["process_status"] = "error"
+				data["error"] = "invalid response from gateway"
+			} else {
+				// Gateway is running and responded properly — merge health data
+				for k, v := range healthData {
+					data[k] = v
+				}
+				data["process_status"] = "running"
+			}
+		}
+	}
+
+	// Append log data from the buffer
+	appendLogData(r, data)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+// appendLogData reads log_offset and log_run_id query params from the request and
+// populates the response data map with incremental log lines.
+func appendLogData(r *http.Request, data map[string]any) {
+	clientOffset := 0
+	clientRunID := -1
+
+	if v := r.URL.Query().Get("log_offset"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientOffset = n
+		}
+	}
+
+	if v := r.URL.Query().Get("log_run_id"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientRunID = n
+		}
+	}
+
+	runID := gatewayLogs.RunID()
+
+	// If runID is 0 (never reset = never launched from this launcher), report no source
+	if runID == 0 {
+		data["logs"] = []string{}
+		data["log_total"] = 0
+		data["log_run_id"] = 0
+		data["log_source"] = "none"
+		return
+	}
+
+	// If the client's runID doesn't match, send all buffered lines (gateway restarted)
+	offset := clientOffset
+	if clientRunID != runID {
+		offset = 0
+	}
+
+	lines, total, runID := gatewayLogs.LinesSince(offset)
+	if lines == nil {
+		lines = []string{}
+	}
+
+	data["logs"] = lines
+	data["log_total"] = total
+	data["log_run_id"] = runID
+	data["log_source"] = "launcher"
+}
@@ -0,0 +1,196 @@
+package server
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const DefaultPort = "18800"
+
+// providerStatus represents the auth status of a single provider in API responses.
+type providerStatus struct {
+	Provider   string `json:"provider"`
+	AuthMethod string `json:"auth_method"`
+	Status     string `json:"status"`
+	AccountID  string `json:"account_id,omitempty"`
+	Email      string `json:"email,omitempty"`
+	ProjectID  string `json:"project_id,omitempty"`
+	ExpiresAt  string `json:"expires_at,omitempty"`
+}
+
+// ── Route registration ───────────────────────────────────────────
+
+func RegisterConfigAPI(mux *http.ServeMux, absPath string) {
+	// GET /api/config — read config
+	mux.HandleFunc("GET /api/config", func(w http.ResponseWriter, r *http.Request) {
+		cfg, err := config.LoadConfig(absPath)
+		if err != nil {
+			http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		resp := map[string]any{
+			"config": cfg,
+			"path":   absPath,
+		}
+		enc := json.NewEncoder(w)
+		enc.SetIndent("", "  ")
+		if err := enc.Encode(resp); err != nil {
+			log.Printf("Failed to encode response: %v", err)
+		}
+	})
+
+	// PUT /api/config — save config
+	mux.HandleFunc("PUT /api/config", func(w http.ResponseWriter, r *http.Request) {
+		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+		if err != nil {
+			http.Error(w, "Failed to read request body", http.StatusBadRequest)
+			return
+		}
+		defer r.Body.Close()
+
+		var cfg config.Config
+		if err := json.Unmarshal(body, &cfg); err != nil {
+			http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+			return
+		}
+
+		if err := config.SaveConfig(absPath, &cfg); err != nil {
+			http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+	})
+}
+
+func RegisterAuthAPI(mux *http.ServeMux, absPath string) {
+	// GET /api/auth/status — all authenticated providers + pending login state
+	mux.HandleFunc("GET /api/auth/status", func(w http.ResponseWriter, r *http.Request) {
+		store, err := auth.LoadStore()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("Failed to load auth store: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		result := []providerStatus{}
+		for name, cred := range store.Credentials {
+			status := "active"
+			if cred.IsExpired() {
+				status = "expired"
+			} else if cred.NeedsRefresh() {
+				status = "needs_refresh"
+			}
+			ps := providerStatus{
+				Provider:   name,
+				AuthMethod: cred.AuthMethod,
+				Status:     status,
+				AccountID:  cred.AccountID,
+				Email:      cred.Email,
+				ProjectID:  cred.ProjectID,
+			}
+			if !cred.ExpiresAt.IsZero() {
+				ps.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
+			}
+			result = append(result, ps)
+		}
+
+		// Include pending device code state
+		var pendingDevice map[string]any
+		activeDeviceSessionMu.Lock()
+		if activeDeviceSession != nil {
+			activeDeviceSession.mu.Lock()
+			pendingDevice = map[string]any{
+				"provider":   activeDeviceSession.Provider,
+				"status":     activeDeviceSession.Status,
+				"device_url": activeDeviceSession.Info.VerifyURL,
+				"user_code":  activeDeviceSession.Info.UserCode,
+			}
+			if activeDeviceSession.Error != "" {
+				pendingDevice["error"] = activeDeviceSession.Error
+			}
+			if activeDeviceSession.Done {
+				activeDeviceSession.mu.Unlock()
+				activeDeviceSession = nil
+			} else {
+				activeDeviceSession.mu.Unlock()
+			}
+		}
+		activeDeviceSessionMu.Unlock()
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"providers":      result,
+			"pending_device": pendingDevice,
+		})
+	})
+
+	// POST /api/auth/login — initiate provider login
+	mux.HandleFunc("POST /api/auth/login", func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Provider string `json:"provider"`
+			Token    string `json:"token,omitempty"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, "Invalid request body", http.StatusBadRequest)
+			return
+		}
+
+		switch req.Provider {
+		case "openai":
+			handleOpenAILogin(w, absPath)
+		case "anthropic":
+			handleAnthropicLogin(w, req.Token, absPath)
+		case "google-antigravity", "antigravity":
+			handleGoogleAntigravityLogin(w, r, absPath)
+		default:
+			http.Error(
+				w,
+				fmt.Sprintf(
+					"Unsupported provider: %s (supported: openai, anthropic, google-antigravity)",
+					req.Provider,
+				),
+				http.StatusBadRequest,
+			)
+		}
+	})
+
+	// POST /api/auth/logout — logout a provider
+	mux.HandleFunc("POST /api/auth/logout", func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			Provider string `json:"provider"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			http.Error(w, "Invalid request body", http.StatusBadRequest)
+			return
+		}
+
+		if req.Provider == "" {
+			if err := auth.DeleteAllCredentials(); err != nil {
+				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
+				return
+			}
+			clearAllAuthMethodsInConfig(absPath)
+		} else {
+			if err := auth.DeleteCredential(req.Provider); err != nil {
+				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
+				return
+			}
+			clearAuthMethodInConfig(absPath, req.Provider)
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+	})
+
+	// GET /auth/callback — OAuth browser callback for Google Antigravity
+	mux.HandleFunc("GET /auth/callback", handleOAuthCallback)
+}
@@ -0,0 +1,247 @@
+package server
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ── Config API tests ─────────────────────────────────────────────
+
+func setupConfigMux(t *testing.T, cfg *config.Config) (*http.ServeMux, string) {
+	t.Helper()
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.json")
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal config: %v", err)
+	}
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	mux := http.NewServeMux()
+	RegisterConfigAPI(mux, path)
+	RegisterAuthAPI(mux, path)
+	return mux, path
+}
+
+func TestGetConfig(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
+		},
+	}
+	mux, path := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("GET", "/api/config", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("GET /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp struct {
+		Config config.Config `json:"config"`
+		Path   string        `json:"path"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+
+	if resp.Path != path {
+		t.Errorf("expected path %q, got %q", path, resp.Path)
+	}
+	if len(resp.Config.ModelList) != 1 {
+		t.Errorf("expected 1 model, got %d", len(resp.Config.ModelList))
+	}
+}
+
+func TestGetConfig_MissingFile_ReturnsDefault(t *testing.T) {
+	mux := http.NewServeMux()
+	RegisterConfigAPI(mux, "/tmp/nonexistent-picoclaw-launcher-test/config.json")
+
+	req := httptest.NewRequest("GET", "/api/config", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	// LoadConfig returns a default empty config when file is missing
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 for missing file (default config), got %d", w.Code)
+	}
+}
+
+func TestPutConfig(t *testing.T) {
+	cfg := &config.Config{}
+	mux, path := setupConfigMux(t, cfg)
+
+	newCfg := config.Config{
+		ModelList: []config.ModelConfig{
+			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
+		},
+	}
+	body, _ := json.Marshal(newCfg)
+
+	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader(string(body)))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("PUT /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	saved, err := config.LoadConfig(path)
+	if err != nil {
+		t.Fatalf("load saved config: %v", err)
+	}
+	if len(saved.ModelList) != 1 {
+		t.Fatalf("expected 1 model saved, got %d", len(saved.ModelList))
+	}
+	if saved.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
+		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", saved.ModelList[0].Model)
+	}
+}
+
+func TestPutConfig_InvalidJSON(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader("{invalid"))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for invalid JSON, got %d", w.Code)
+	}
+}
+
+// ── Auth API tests ───────────────────────────────────────────────
+
+func TestAuthStatus(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("GET", "/api/auth/status", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("GET /api/auth/status: expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp struct {
+		Providers     []providerStatus `json:"providers"`
+		PendingDevice map[string]any   `json:"pending_device"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+
+	// providers should be a non-nil list (could be empty)
+	if resp.Providers == nil {
+		t.Error("providers should not be nil")
+	}
+}
+
+func TestAuthLogin_UnsupportedProvider(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	body := `{"provider": "unsupported"}`
+	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for unsupported provider, got %d", w.Code)
+	}
+}
+
+func TestAuthLogin_AnthropicNoToken(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	body := `{"provider": "anthropic"}`
+	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for anthropic without token, got %d", w.Code)
+	}
+}
+
+func TestAuthLogin_InvalidBody(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for invalid JSON body, got %d", w.Code)
+	}
+}
+
+func TestAuthLogout_InvalidBody(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("POST", "/api/auth/logout", strings.NewReader("{bad"))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for invalid body, got %d", w.Code)
+	}
+}
+
+func TestOAuthCallback_InvalidState(t *testing.T) {
+	cfg := &config.Config{}
+	mux, _ := setupConfigMux(t, cfg)
+
+	req := httptest.NewRequest("GET", "/auth/callback?state=invalid&code=test", nil)
+	w := httptest.NewRecorder()
+	mux.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400 for invalid state, got %d", w.Code)
+	}
+}
+
+// ── Utility tests ────────────────────────────────────────────────
+
+func TestDefaultConfigPath(t *testing.T) {
+	path := DefaultConfigPath()
+	if path == "" {
+		t.Error("defaultConfigPath should not return empty")
+	}
+	if !strings.HasSuffix(path, filepath.Join(".picoclaw", "config.json")) {
+		t.Errorf("expected path ending with .picoclaw/config.json, got %q", path)
+	}
+}
+
+func TestGetLocalIP(t *testing.T) {
+	// Just ensure it doesn't panic; IP may or may not be available
+	ip := GetLocalIP()
+	if ip != "" {
+		// If returned, should look like an IP
+		if !strings.Contains(ip, ".") {
+			t.Errorf("getLocalIP returned non-IPv4 looking string: %q", ip)
+		}
+	}
+}
@@ -0,0 +1,28 @@
+package server
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+)
+
+func DefaultConfigPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "config.json"
+	}
+	return filepath.Join(home, ".picoclaw", "config.json")
+}
+
+func GetLocalIP() string {
+	addrs, err := net.InterfaceAddrs()
+	if err != nil {
+		return ""
+	}
+	for _, a := range addrs {
+		if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
+			return ipnet.IP.String()
+		}
+	}
+	return ""
+}
@@ -0,0 +1,127 @@
+// PicoClaw Launcher - Standalone HTTP service
+//
+// Provides a web-based JSON editor for picoclaw config files,
+// with OAuth provider authentication support.
+//
+// Usage:
+//
+//	go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
+//	./picoclaw-launcher [config.json]
+//	./picoclaw-launcher -public config.json
+
+package main
+
+import (
+	"embed"
+	"flag"
+	"fmt"
+	"io/fs"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher/internal/server"
+)
+
+//go:embed internal/ui/index.html
+var staticFiles embed.FS
+
+func main() {
+	public := flag.Bool("public", false, "Listen on all interfaces (0.0.0.0) instead of localhost only")
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "PicoClaw Launcher - A web-based configuration editor\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: %s [options] [config.json]\n\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "Arguments:\n")
+		fmt.Fprintf(os.Stderr, "  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)\n\n")
+		fmt.Fprintf(os.Stderr, "Options:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(os.Stderr, "\nExamples:\n")
+		fmt.Fprintf(os.Stderr, "  %s                          Use default config path\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "  %s ./config.json             Specify a config file\n", os.Args[0])
+		fmt.Fprintf(
+			os.Stderr,
+			"  %s -public ./config.json     Allow access from other devices on the network\n",
+			os.Args[0],
+		)
+	}
+	flag.Parse()
+
+	configPath := server.DefaultConfigPath()
+	if flag.NArg() > 0 {
+		configPath = flag.Arg(0)
+	}
+
+	absPath, err := filepath.Abs(configPath)
+	if err != nil {
+		log.Fatalf("Failed to resolve config path: %v", err)
+	}
+
+	var addr string
+	if *public {
+		addr = "0.0.0.0:" + server.DefaultPort
+	} else {
+		addr = "127.0.0.1:" + server.DefaultPort
+	}
+
+	mux := http.NewServeMux()
+	server.RegisterConfigAPI(mux, absPath)
+	server.RegisterAuthAPI(mux, absPath)
+	server.RegisterProcessAPI(mux, absPath)
+
+	staticFS, err := fs.Sub(staticFiles, "internal/ui")
+	if err != nil {
+		log.Fatalf("Failed to create sub filesystem: %v", err)
+	}
+	mux.Handle("/", http.FileServer(http.FS(staticFS)))
+
+	// Print startup banner
+	fmt.Println("=============================================")
+	fmt.Println("  PicoClaw Launcher")
+	fmt.Println("=============================================")
+	fmt.Printf("  Config file : %s\n", absPath)
+	fmt.Printf("  Listen addr : %s\n\n", addr)
+	fmt.Println("  Open the following URL in your browser")
+	fmt.Println("  to view and edit the configuration:")
+	fmt.Println()
+	fmt.Printf("    >> http://localhost:%s <<\n", server.DefaultPort)
+	if *public {
+		if ip := server.GetLocalIP(); ip != "" {
+			fmt.Printf("    >> http://%s:%s <<\n", ip, server.DefaultPort)
+		}
+	}
+	fmt.Println()
+	// fmt.Println("=============================================")
+
+	go func() {
+		// Wait briefly to ensure the server is ready before opening the browser
+		time.Sleep(500 * time.Millisecond)
+		url := "http://localhost:" + server.DefaultPort
+		if err := openBrowser(url); err != nil {
+			log.Printf("Warning: Failed to auto-open browser: %v\n", err)
+		}
+	}()
+
+	if err := http.ListenAndServe(addr, mux); err != nil {
+		log.Fatalf("Server failed: %v", err)
+	}
+}
+
+// openBrowser automatically opens the given URL in the default browser.
+func openBrowser(url string) error {
+	var err error
+	switch runtime.GOOS {
+	case "linux":
+		err = exec.Command("xdg-open", url).Start()
+	case "windows":
+		err = exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
+	case "darwin":
+		err = exec.Command("open", url).Start()
+	default:
+		err = fmt.Errorf("unsupported platform")
+	}
+	return err
+}
@@ -0,0 +1,22 @@
+{
+  "RT_GROUP_ICON": {
+    "APP": {
+      "0000": "../icon.ico"
+    }
+  },
+  "RT_MANIFEST": {
+    "#1": {
+      "0409": {
+        "identity": {
+          "name": "PicoClaw Launcher",
+          "version": "0.0.0.0"
+        },
+        "description": "PicoClaw Launcher - Web-based configuration editor",
+        "minimum-os": "win7",
+        "execution-level": "asInvoker",
+        "dpi-awareness": "system",
+        "use-common-controls-v6": true
+      }
+    }
+  }
+}
@@ -48,6 +48,7 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
 	}

 	msgBus := bus.NewMessageBus()
+	defer msgBus.Close()
 	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)

 	// Print agent startup info (only for interactive mode)
@@ -2,29 +2,40 @@ package gateway

 import (
 	"context"
-	"errors"
 	"fmt"
-	"net/http"
+	"log"
 	"os"
 	"os/signal"
 	"path/filepath"
-	"strings"
 	"time"

 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/agent"
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	_ "github.com/sipeed/picoclaw/pkg/channels/dingtalk"
+	_ "github.com/sipeed/picoclaw/pkg/channels/discord"
+	_ "github.com/sipeed/picoclaw/pkg/channels/feishu"
+	_ "github.com/sipeed/picoclaw/pkg/channels/line"
+	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
+	_ "github.com/sipeed/picoclaw/pkg/channels/onebot"
+	_ "github.com/sipeed/picoclaw/pkg/channels/pico"
+	_ "github.com/sipeed/picoclaw/pkg/channels/qq"
+	_ "github.com/sipeed/picoclaw/pkg/channels/slack"
+	_ "github.com/sipeed/picoclaw/pkg/channels/telegram"
+	_ "github.com/sipeed/picoclaw/pkg/channels/wecom"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/cron"
 	"github.com/sipeed/picoclaw/pkg/devices"
 	"github.com/sipeed/picoclaw/pkg/health"
 	"github.com/sipeed/picoclaw/pkg/heartbeat"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/state"
 	"github.com/sipeed/picoclaw/pkg/tools"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )

 func gatewayCmd(debug bool) error {
@@ -105,49 +116,23 @@ func gatewayCmd(debug bool) error {
 		return tools.SilentResult(response)
 	})

-	channelManager, err := channels.NewManager(cfg, msgBus)
+	// Create media store for file lifecycle management with TTL cleanup
+	mediaStore := media.NewFileMediaStoreWithCleanup(media.MediaCleanerConfig{
+		Enabled:  cfg.Tools.MediaCleanup.Enabled,
+		MaxAge:   time.Duration(cfg.Tools.MediaCleanup.MaxAge) * time.Minute,
+		Interval: time.Duration(cfg.Tools.MediaCleanup.Interval) * time.Minute,
+	})
+	mediaStore.Start()
+
+	channelManager, err := channels.NewManager(cfg, msgBus, mediaStore)
 	if err != nil {
+		mediaStore.Stop()
 		return fmt.Errorf("error creating channel manager: %w", err)
 	}

-	// Inject channel manager into agent loop for command handling
+	// Inject channel manager and media store into agent loop
 	agentLoop.SetChannelManager(channelManager)
-
-	var transcriber *voice.GroqTranscriber
-	groqAPIKey := cfg.Providers.Groq.APIKey
-	if groqAPIKey == "" {
-		for _, mc := range cfg.ModelList {
-			if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey != "" {
-				groqAPIKey = mc.APIKey
-				break
-			}
-		}
-	}
-	if groqAPIKey != "" {
-		transcriber = voice.NewGroqTranscriber(groqAPIKey)
-		logger.InfoC("voice", "Groq voice transcription enabled")
-	}
-
-	if transcriber != nil {
-		if telegramChannel, ok := channelManager.GetChannel("telegram"); ok {
-			if tc, ok := telegramChannel.(*channels.TelegramChannel); ok {
-				tc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Telegram channel")
-			}
-		}
-		if discordChannel, ok := channelManager.GetChannel("discord"); ok {
-			if dc, ok := discordChannel.(*channels.DiscordChannel); ok {
-				dc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Discord channel")
-			}
-		}
-		if slackChannel, ok := channelManager.GetChannel("slack"); ok {
-			if sc, ok := slackChannel.(*channels.SlackChannel); ok {
-				sc.SetTranscriber(transcriber)
-				logger.InfoC("voice", "Groq transcription attached to Slack channel")
-			}
-		}
-	}
+	agentLoop.SetMediaStore(mediaStore)

 	enabledChannels := channelManager.GetEnabledChannels()
 	if len(enabledChannels) > 0 {
@@ -184,16 +169,16 @@ func gatewayCmd(debug bool) error {
 		fmt.Println("✓ Device event service started")
 	}

+	// Setup shared HTTP server with health endpoints and webhook handlers
+	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+	addr := fmt.Sprintf("%s:%d", cfg.Gateway.Host, cfg.Gateway.Port)
+	channelManager.SetupHTTPServer(addr, healthServer)
+
 	if err := channelManager.StartAll(ctx); err != nil {
 		fmt.Printf("Error starting channels: %v\n", err)
+		return err
 	}

-	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
-	go func() {
-		if err := healthServer.Start(); err != nil && !errors.Is(err, http.ErrServerClosed) {
-			logger.ErrorCF("health", "Health server error", map[string]any{"error": err.Error()})
-		}
-	}()
 	fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)

 	go agentLoop.Run(ctx)
@@ -207,12 +192,19 @@ func gatewayCmd(debug bool) error {
 		cp.Close()
 	}
 	cancel()
-	healthServer.Stop(context.Background())
+	msgBus.Close()
+
+	// Use a fresh context with timeout for graceful shutdown,
+	// since the original ctx is already canceled.
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer shutdownCancel()
+
+	channelManager.StopAll(shutdownCtx)
 	deviceService.Stop()
 	heartbeatService.Stop()
 	cronService.Stop()
+	mediaStore.Stop()
 	agentLoop.Stop()
-	channelManager.StopAll(ctx)
 	fmt.Println("✓ Gateway stopped")

 	return nil
@@ -232,7 +224,11 @@ func setupCronTool(
 	cronService := cron.NewCronService(cronStorePath, nil)

 	// Create and register CronTool
-	cronTool := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
+	cronTool, err := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
+	if err != nil {
+		log.Fatalf("Critical error during CronTool initialization: %v", err)
+	}
+
 	agentLoop.RegisterTool(cronTool)

 	// Set the onJob handler
@@ -19,6 +19,9 @@ var (
 )

 func GetConfigPath() string {
+	if configPath := os.Getenv("PICOCLAW_CONFIG"); configPath != "" {
+		return configPath
+	}
 	home, _ := os.UserHomeDir()
 	return filepath.Join(home, ".picoclaw", "config.json")
 }
@@ -95,3 +95,13 @@ func TestGetConfigPath_Windows(t *testing.T) {
 func TestGetVersion(t *testing.T) {
 	assert.Equal(t, "dev", GetVersion())
 }
+
+func TestGetConfigPath_WithEnv(t *testing.T) {
+	t.Setenv("PICOCLAW_CONFIG", "/tmp/custom/config.json")
+	t.Setenv("HOME", "/tmp/home") // Also set home to ensure env is preferred
+
+	got := GetConfigPath()
+	want := "/tmp/custom/config.json"
+
+	assert.Equal(t, want, got)
+}
@@ -11,19 +11,21 @@ func NewMigrateCommand() *cobra.Command {

 	cmd := &cobra.Command{
 		Use:   "migrate",
-		Short: "Migrate from OpenClaw to PicoClaw",
+		Short: "Migrate from xxxclaw(openclaw, etc.) to picoclaw",
 		Args:  cobra.NoArgs,
 		Example: `  picoclaw migrate
+  picoclaw migrate --from openclaw
  picoclaw migrate --dry-run
  picoclaw migrate --refresh
  picoclaw migrate --force`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			result, err := migrate.Run(opts)
+			m := migrate.NewMigrateInstance(opts)
+			result, err := m.Run(opts)
 			if err != nil {
 				return err
 			}
 			if !opts.DryRun {
-				migrate.PrintSummary(result)
+				m.PrintSummary(result)
 			}
 			return nil
 		},
@@ -31,6 +33,8 @@ func NewMigrateCommand() *cobra.Command {

 	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false,
 		"Show what would be migrated without making changes")
+	cmd.Flags().StringVar(&opts.Source, "from", "openclaw",
+		"Source to migrate from (e.g., openclaw)")
 	cmd.Flags().BoolVar(&opts.Refresh, "refresh", false,
 		"Re-sync workspace files from OpenClaw (repeatable)")
 	cmd.Flags().BoolVar(&opts.ConfigOnly, "config-only", false,
@@ -39,10 +43,10 @@ func NewMigrateCommand() *cobra.Command {
 		"Only migrate workspace files, skip config")
 	cmd.Flags().BoolVar(&opts.Force, "force", false,
 		"Skip confirmation prompts")
-	cmd.Flags().StringVar(&opts.OpenClawHome, "openclaw-home", "",
-		"Override OpenClaw home directory (default: ~/.openclaw)")
-	cmd.Flags().StringVar(&opts.PicoClawHome, "picoclaw-home", "",
-		"Override PicoClaw home directory (default: ~/.picoclaw)")
+	cmd.Flags().StringVar(&opts.SourceHome, "source-home", "",
+		"Override source home directory (default: ~/.openclaw)")
+	cmd.Flags().StringVar(&opts.TargetHome, "target-home", "",
+		"Override target home directory (default: ~/.picoclaw)")

 	return cmd
 }
@@ -13,7 +13,7 @@ func TestNewMigrateCommand(t *testing.T) {
 	require.NotNil(t, cmd)

 	assert.Equal(t, "migrate", cmd.Use)
-	assert.Equal(t, "Migrate from OpenClaw to PicoClaw", cmd.Short)
+	assert.Equal(t, "Migrate from xxxclaw(openclaw, etc.) to picoclaw", cmd.Short)

 	assert.Len(t, cmd.Aliases, 0)

@@ -33,6 +33,6 @@ func TestNewMigrateCommand(t *testing.T) {
 	assert.NotNil(t, cmd.Flags().Lookup("config-only"))
 	assert.NotNil(t, cmd.Flags().Lookup("workspace-only"))
 	assert.NotNil(t, cmd.Flags().Lookup("force"))
-	assert.NotNil(t, cmd.Flags().Lookup("openclaw-home"))
-	assert.NotNil(t, cmd.Flags().Lookup("picoclaw-home"))
+	assert.NotNil(t, cmd.Flags().Lookup("source-home"))
+	assert.NotNil(t, cmd.Flags().Lookup("target-home"))
 }
@@ -0,0 +1,25 @@
+package onboard
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestCopyEmbeddedToTargetUsesAgentsMarkdown(t *testing.T) {
+	targetDir := t.TempDir()
+
+	if err := copyEmbeddedToTarget(targetDir); err != nil {
+		t.Fatalf("copyEmbeddedToTarget() error = %v", err)
+	}
+
+	agentsPath := filepath.Join(targetDir, "AGENTS.md")
+	if _, err := os.Stat(agentsPath); err != nil {
+		t.Fatalf("expected %s to exist: %v", agentsPath, err)
+	}
+
+	legacyPath := filepath.Join(targetDir, "AGENT.md")
+	if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+		t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+	}
+}
@@ -71,7 +71,7 @@ func NewSkillsCommand() *cobra.Command {
 		newInstallBuiltinCommand(workspaceFn),
 		newListBuiltinCommand(),
 		newRemoveCommand(installerFn),
-		newSearchCommand(installerFn),
+		newSearchCommand(),
 		newShowCommand(loaderFn),
 	)

@@ -15,6 +15,8 @@ import (
 	"github.com/sipeed/picoclaw/pkg/utils"
 )

+const skillsSearchMaxResults = 20
+
 func skillsListCmd(loader *skills.SkillsLoader) {
 	allSkills := loader.ListSkills()

@@ -215,34 +217,43 @@ func skillsListBuiltinCmd() {
 	}
 }

-func skillsSearchCmd(installer *skills.SkillInstaller) {
+func skillsSearchCmd(query string) {
 	fmt.Println("Searching for available skills...")

+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		fmt.Printf("✗ Failed to load config: %v\n", err)
+		return
+	}
+
+	registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+		MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+		ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+	})
+
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()

-	availableSkills, err := installer.ListAvailableSkills(ctx)
+	results, err := registryMgr.SearchAll(ctx, query, skillsSearchMaxResults)
 	if err != nil {
 		fmt.Printf("✗ Failed to fetch skills list: %v\n", err)
 		return
 	}

-	if len(availableSkills) == 0 {
+	if len(results) == 0 {
 		fmt.Println("No skills available.")
 		return
 	}

-	fmt.Printf("\nAvailable Skills (%d):\n", len(availableSkills))
+	fmt.Printf("\nAvailable Skills (%d):\n", len(results))
 	fmt.Println("--------------------")
-	for _, skill := range availableSkills {
-		fmt.Printf("  📦 %s\n", skill.Name)
-		fmt.Printf("     %s\n", skill.Description)
-		fmt.Printf("     Repo: %s\n", skill.Repository)
-		if skill.Author != "" {
-			fmt.Printf("     Author: %s\n", skill.Author)
-		}
-		if len(skill.Tags) > 0 {
-			fmt.Printf("     Tags: %v\n", skill.Tags)
+	for _, result := range results {
+		fmt.Printf("  📦 %s\n", result.DisplayName)
+		fmt.Printf("     %s\n", result.Summary)
+		fmt.Printf("     Slug: %s\n", result.Slug)
+		fmt.Printf("     Registry: %s\n", result.RegistryName)
+		if result.Version != "" {
+			fmt.Printf("     Version: %s\n", result.Version)
 		}
 		fmt.Println()
 	}
@@ -2,20 +2,19 @@ package skills

 import (
 	"github.com/spf13/cobra"
-
-	"github.com/sipeed/picoclaw/pkg/skills"
 )

-func newSearchCommand(installerFn func() (*skills.SkillInstaller, error)) *cobra.Command {
+func newSearchCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "search",
+		Use:   "search [query]",
 		Short: "Search available skills",
-		RunE: func(_ *cobra.Command, _ []string) error {
-			installer, err := installerFn()
-			if err != nil {
-				return err
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			query := ""
+			if len(args) == 1 {
+				query = args[0]
 			}
-			skillsSearchCmd(installer)
+			skillsSearchCmd(query)
 			return nil
 		},
 	}
@@ -8,11 +8,11 @@ import (
 )

 func TestNewSearchSubcommand(t *testing.T) {
-	cmd := newSearchCommand(nil)
+	cmd := newSearchCommand()

 	require.NotNil(t, cmd)

-	assert.Equal(t, "search", cmd.Use)
+	assert.Equal(t, "search [query]", cmd.Use)
 	assert.Equal(t, "Search available skills", cmd.Short)

 	assert.Nil(t, cmd.Run)
@@ -52,31 +52,40 @@
      "proxy": "",
      "allow_from": [
        "YOUR_USER_ID"
-      ]
+      ],
+      "reasoning_channel_id": ""
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "proxy": "",
      "allow_from": [],
-      "mention_only": false
+      "group_trigger": {
+        "mention_only": false
+      },
+      "reasoning_channel_id": ""
    },
    "qq": {
      "enabled": false,
      "app_id": "YOUR_QQ_APP_ID",
      "app_secret": "YOUR_QQ_APP_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "maixcam": {
      "enabled": false,
      "host": "0.0.0.0",
      "port": 18790,
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "ws://localhost:3001",
-      "allow_from": []
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "feishu": {
      "enabled": false,
@@ -84,28 +93,30 @@
      "app_secret": "",
      "encrypt_key": "",
      "verification_token": "",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "slack": {
      "enabled": false,
      "bot_token": "xoxb-YOUR-BOT-TOKEN",
      "app_token": "xapp-YOUR-APP-TOKEN",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "line": {
      "enabled": false,
      "channel_secret": "YOUR_LINE_CHANNEL_SECRET",
      "channel_access_token": "YOUR_LINE_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "onebot": {
      "enabled": false,
@@ -113,7 +124,8 @@
      "access_token": "",
      "reconnect_interval": 5,
      "group_trigger_prefix": [],
-      "allow_from": []
+      "allow_from": [],
+      "reasoning_channel_id": ""
    },
    "wecom": {
      "_comment": "WeCom Bot (智能机器人) - Easier setup, supports group chats",
@@ -121,11 +133,10 @@
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
    },
    "wecom_app": {
      "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only. See docs/wecom-app-configuration.md",
@@ -135,11 +146,10 @@
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": [],
-      "reply_timeout": 5
+      "reply_timeout": 5,
+      "reasoning_channel_id": ""
    }
  },
  "providers": {
@@ -11,7 +11,9 @@ Discord 是一个专为社区设计的免费语音、视频和文本聊天应用
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"],
-      "mention_only": false
+      "group_trigger": {
+        "mention_only": false
+      }
    }
  }
 }
@@ -22,7 +24,7 @@ Discord 是一个专为社区设计的免费语音、视频和文本聊天应用
 | enabled      | bool   | 是   | 是否启用 Discord 频道            |
 | token        | string | 是   | Discord 机器人 Token             |
 | allow_from   | array  | 否   | 用户ID白名单，空表示允许所有用户 |
-| mention_only | bool   | 否   | 是否仅响应提及机器人的消息       |
+| group_trigger | object | 否   | 群组触发设置（示例: { "mention_only": false }） |

 ## 设置流程

@@ -11,8 +11,6 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18791,
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
@@ -25,9 +23,7 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
 | enabled              | bool   | 是   | 是否启用 LINE Channel                      |
 | channel_secret       | string | 是   | LINE Messaging API 的 Channel Secret       |
 | channel_access_token | string | 是   | LINE Messaging API 的 Channel Access Token |
-| webhook_host         | string | 是   | Webhook 监听的主机地址 (通常为 0.0.0.0)    |
-| webhook_port         | int    | 是   | Webhook 监听的端口 (默认为 18791)          |
-| webhook_path         | string | 是   | Webhook 的路径 (默认为 /webhook/line)      |
+| webhook_path         | string | 否   | Webhook 的路径 (默认为 /webhook/line)      |
 | allow_from           | array  | 否   | 用户ID白名单，空表示允许所有用户           |

 ## 设置流程
@@ -35,7 +31,8 @@ PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的
 1. 前往 [LINE Developers Console](https://developers.line.biz/console/) 创建一个服务提供商和一个 Messaging API Channel
 2. 获取 Channel Secret 和 Channel Access Token
 3. 配置Webhook:
-   - Line要求Webhook必须使用HTTPS协议，因此需要部署一个支持HTTPS的服务器，或者使用反向代理工具如ngrok将本地服务器暴露到公网
-   - 将 Webhook URL 设置为 `https://your-domain.com/webhook/line`
+   - LINE 要求 Webhook 必须使用 HTTPS 协议，因此需要部署一个支持 HTTPS 的服务器，或者使用反向代理工具如 ngrok 将本地服务器暴露到公网
+   - PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790
+   - 将 Webhook URL 设置为 `https://your-domain.com/webhook/line`，然后将外部域名反向代理到本机的 Gateway（默认端口 18790）
   - 启用 Webhook 并验证 URL
 4. 将 Channel Secret 和 Channel Access Token 填入配置文件中
@@ -14,8 +14,6 @@
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": [],
      "reply_timeout": 5
@@ -31,8 +29,6 @@
 | agent_id         | int    | 是   | 应用程序代理 ID                          |
 | token            | string | 是   | 回调验证令牌                             |
 | encoding_aes_key | string | 是   | 43 字符 AES 密钥                         |
-| webhook_host     | string | 否   | HTTP 服务器绑定地址                      |
-| webhook_port     | int    | 否   | HTTP 服务器端口（默认：18792）           |
 | webhook_path     | string | 否   | Webhook 路径（默认：/webhook/wecom-app） |
 | allow_from       | array  | 否   | 用户 ID 白名单                           |
 | reply_timeout    | int    | 否   | 回复超时时间（秒）                       |
@@ -45,3 +41,5 @@
 4. 在应用设置中配置“接收消息”，获取 Token 和 EncodingAESKey
 5. 设置回调 URL 为 `http://<your-server-ip>:<port>/webhook/wecom-app`
 6. 将 CorpID, Secret, AgentID 等信息填入配置文件
+
+   注意: PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790。如需从公网接收回调，请把外部域名反向代理到 Gateway（默认端口 18790）。
@@ -12,8 +12,6 @@
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18793,
      "webhook_path": "/webhook/wecom",
      "allow_from": [],
      "reply_timeout": 5
@@ -27,8 +25,6 @@
 | token            | string | 是   | 签名验证代币                                 |
 | encoding_aes_key | string | 是   | 用于解密的 43 字符 AES 密钥                  |
 | webhook_url      | string | 是   | 用于发送回复的企业微信群聊机器人 Webhook URL |
-| webhook_host     | string | 否   | HTTP 服务器绑定地址（默认：0.0.0.0）         |
-| webhook_port     | int    | 否   | HTTP 服务器端口（默认：18793）               |
 | webhook_path     | string | 否   | Webhook 端点路径（默认：/webhook/wecom）     |
 | allow_from       | array  | 否   | 用户 ID 白名单（空值 = 允许所有用户）        |
 | reply_timeout    | int    | 否   | 回复超时时间（单位：秒，默认值：5）          |
@@ -39,3 +35,5 @@
 2. 获取 Webhook URL
 3. (如需接收消息) 在机器人配置页面设置接收消息的 API 地址（回调地址）以及 Token 和 EncodingAESKey
 4. 将相关信息填入配置文件
+
+   注意: PicoClaw 现在使用共享的 Gateway HTTP 服务器来接收所有渠道的 webhook 回调，默认监听地址为 127.0.0.1:18790。如需从公网接收回调，请把外部域名反向代理到 Gateway（默认端口 18790）。
@@ -0,0 +1,61 @@
+# Issue #783 调研与修复执行文档
+
+## 1. 问题澄清（已确认）
+
+- 现象：当 `agents.*.model.primary/fallbacks` 使用 `model_name` 别名（如 `step-3.5-flash`）时，fallback 链路将别名当作真实 `provider/model` 解析，导致 `provider` 可能为空、`model` 可能错误。
+- 根因：`ResolveCandidates` 仅对字符串做 `ParseModelRef`，未先通过 `model_list` 将别名映射到真实 `model` 字段。
+- 影响：
+  - fallback 执行可能把别名直接发给 OpenAI-compatible provider，触发 `Unknown Model`。
+  - `defaults.provider` 为空时，日志出现 `provider=` 空值。
+
+## 2. 本次目标
+
+- 修复 fallback 候选解析：优先通过 `model_list` 解析别名。
+- 兼容旧行为：若未命中 `model_list`，继续走原有 `ParseModelRef` 兜底。
+- 补充测试：覆盖别名、嵌套路径模型（如 `openrouter/stepfun/...`）、空默认 provider。
+- 验证代码风格：与当前仓库风格保持一致（命名、错误处理、测试结构）。
+
+## 3. 联网最佳实践调研结论（已完成）
+
+- [x] 查阅 OpenAI-compatible 网关（如 OpenRouter）对 `model` 字段的推荐处理。
+- [x] 查阅多 provider/fallback 设计最佳实践（候选解析、日志可观测性）。
+- [x] 将外部建议映射为本仓库可执行约束。
+
+外部参考要点（来自 OpenRouter/LiteLLM/Cloudflare AI Gateway 等官方文档）：
+
+- 优先显式配置，不依赖字符串切分推断 provider。
+- 对网关模型标识应保留完整路径语义，避免截断导致 Unknown Model。
+- fallback 与 primary 应复用同一解析策略，避免“主路径正确、降级路径错误”。
+
+参考链接：
+
+- OpenRouter Provider Routing: https://openrouter.ai/docs/guides/routing/provider-selection
+- OpenRouter Model Fallbacks: https://openrouter.ai/docs/guides/routing/model-fallbacks
+- OpenRouter Chat Completion API: https://openrouter.ai/docs/api-reference/chat-completion
+- LiteLLM Router Architecture: https://docs.litellm.ai/docs/router_architecture
+- Cloudflare AI Gateway Chat Completion: https://developers.cloudflare.com/ai-gateway/usage/chat-completion/
+
+与本仓库对应的可执行约束：
+
+- 在 fallback candidate 构建阶段先做 `model_name -> model_list.model` 映射。
+- 未命中映射时保留旧解析行为，保证兼容性。
+- 用新增测试锁定“别名 + 嵌套模型路径 + 空默认 provider”场景。
+
+## 4. 实施步骤（顺序执行）
+
+- [x] Step 1: 对齐现有代码模式，定位最小改动点（`pkg/agent` + `pkg/providers`）。
+- [x] Step 2: 实现“基于 model_list 的 fallback 候选解析”。
+- [x] Step 3: 增加/更新单元测试，覆盖 issue 场景。
+- [x] Step 4: 代码风格一致性复核（与现有文件风格对照）。
+- [x] Step 5: 运行质量门禁（LSP + `make check`）。
+
+## 5. 执行记录
+
+- 状态：已完成
+- 已完成改动：
+  - `pkg/providers/fallback.go`：新增 `ResolveCandidatesWithLookup`，并保持 `ResolveCandidates` 向后兼容。
+  - `pkg/agent/instance.go`：在构建 fallback candidates 前，优先通过 `model_list` 解析别名，并对无协议模型补齐默认 `openai/` 前缀后再解析。
+  - `pkg/providers/fallback_test.go`：新增别名解析与去重测试。
+  - `pkg/agent/instance_test.go`：新增 agent 侧别名解析到嵌套模型路径、无协议模型解析测试。
+- 风格对齐检查（完成）：与 `pkg/providers/fallback_test.go`、`pkg/providers/model_ref_test.go` 现有模式一致。
+- 质量验证（完成）：先 `make generate`，后 `make check` 全量通过。
@@ -0,0 +1,43 @@
+# Troubleshooting
+
+## "model ... not found in model_list" or OpenRouter "free is not a valid model ID"
+
+**Symptom:** You see either:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter returns 400: `"free is not a valid model ID"`
+
+**Cause:** The `model` field in your `model_list` entry is what gets sent to the API. For OpenRouter you must use the **full** model ID, not a shorthand.
+
+- **Wrong:** `"model": "free"` → OpenRouter receives `free` and rejects it.
+- **Right:** `"model": "openrouter/free"` → OpenRouter receives `openrouter/free` (auto free-tier routing).
+
+**Fix:** In `~/.picoclaw/config.json` (or your config path):
+
+1. **agents.defaults.model** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
+2. That entry’s **model** must be a valid OpenRouter model ID, for example:
+   - `"openrouter/free"` – auto free-tier
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Example snippet:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Get your key at [OpenRouter Keys](https://openrouter.ai/keys).
@@ -26,7 +26,7 @@

 1. 在应用详情页，点击"接收消息"的"设置API接收"
 2. 填写以下信息：
-   - **URL**: `http://your-server:18792/webhook/wecom-app`
+   - **URL**: `http://your-server:18790/webhook/wecom-app`
   - **Token**: 随机生成或自定义（用于签名验证）
   - **EncodingAESKey**: 点击"随机生成"生成43字符的密钥
 3. 点击"保存"时，企业微信会发送验证请求
@@ -45,8 +45,6 @@
      "agent_id": 1000002,                        // 应用AgentId
      "token": "your_token",                      // 接收消息配置的Token
      "encoding_aes_key": "your_encoding_aes_key", // 接收消息配置的EncodingAESKey
-      "webhook_host": "0.0.0.0",
-      "webhook_port": 18792,
      "webhook_path": "/webhook/wecom-app",
      "allow_from": [],
      "reply_timeout": 5
@@ -62,7 +60,7 @@
 **症状**: 企业微信保存API接收消息时提示验证失败

 **检查项**:
- 确认服务器防火墙已开放 18792 端口
+- 确认服务器防火墙已开放 Gateway 端口（默认 18790）
 - 确认 `corp_id`、`token`、`encoding_aes_key` 配置正确
 - 查看 PicoClaw 日志是否有请求到达

@@ -78,7 +76,7 @@

 **症状**: 启动时提示端口已被占用

-**解决**: 修改 `webhook_port` 为其他端口，如 18794
+**解决**: 修改 `gateway.port` 为其他端口（所有 Webhook 渠道共享同一个 Gateway HTTP 服务器）

 ## 技术细节

@@ -11,6 +11,7 @@ require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
+	github.com/mdp/qrterminal/v3 v3.2.1
 	github.com/mymmrac/telego v1.6.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/openai/openai-go/v3 v3.22.0
@@ -18,15 +19,45 @@ require (
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
 	github.com/tencent-connect/botgo v0.2.1
+	go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4
 	golang.org/x/oauth2 v0.35.0
+	golang.org/x/time v0.14.0
+	google.golang.org/protobuf v1.36.11
+	modernc.org/sqlite v1.46.1
 )

 require (
+	filippo.io/edwards25519 v1.1.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
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/elliotchance/orderedmap/v3 v3.1.0 // indirect
+	github.com/gdamore/encoding v1.0.1 // indirect
+	github.com/gdamore/tcell/v2 v2.13.8 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
+	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/pmezard/go-difflib v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/rivo/tview v0.42.0 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/rs/zerolog v1.34.0 // 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
+	golang.org/x/term v0.40.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
+	modernc.org/libc v1.67.6 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	rsc.io/qr v0.2.0 // indirect
 )

 require (
@@ -1,10 +1,20 @@
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
+filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
+filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
+github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/adhocore/gronx v1.19.6 h1:5KNVcoR9ACgL9HhEqCm5QXsab/gI4QDIybTAWcXDKDc=
 github.com/adhocore/gronx v1.19.6/go.mod h1:7oUY1WAU8rEJWmAxXR2DN0JaO4gi9khSgKjiRypqteg=
+github.com/agnivade/levenshtein v1.2.1 h1:EHBY3UOn1gwdy/VbFwgo4cxecRznFk7fKWN1KOX7eoM=
+github.com/agnivade/levenshtein v1.2.1/go.mod h1:QVVI16kDrtSuwcpd0p1+xMC6Z/VfhtCyDIjcwga4/DU=
+github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
+github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
 github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
 github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/anthropics/anthropic-sdk-go v1.22.1 h1:xbsc3vJKCX/ELDZSpTNfz9wCgrFsamwFewPb1iI0Xh0=
 github.com/anthropics/anthropic-sdk-go v1.22.1/go.mod h1:WTz31rIUHUHqai2UslPpw5CwXrQP3geYBioRV4WOLvE=
+github.com/beeper/argo-go v1.1.2 h1:UQI2G8F+NLfGTOmTUI0254pGKx/HUU/etbUGTJv91Fs=
+github.com/beeper/argo-go v1.1.2/go.mod h1:M+LJAnyowKVQ6Rdj6XYGEn+qcVFkb3R/MUpqkGR0hM4=
 github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+EgjDno=
 github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
@@ -25,14 +35,25 @@ github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
 github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
+github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+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/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
+github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
+github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
+github.com/gdamore/tcell/v2 v2.13.8 h1:Mys/Kl5wfC/GcC5Cx4C2BIQH9dbnhnkPgS9/wF3RlfU=
+github.com/gdamore/tcell/v2 v2.13.8/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
 github.com/github/copilot-sdk/go v0.1.23 h1:uExtO/inZQndCZMiSAA1hvXINiz9tqo/MZgQzFzurxw=
 github.com/github/copilot-sdk/go v0.1.23/go.mod h1:GdwwBfMbm9AABLEM3x5IZKw4ZfwCYxZ1BgyytmZenQ0=
 github.com/go-redis/redis/v8 v8.11.4/go.mod h1:2Z2wHZXdQpCDXEGzqMockDpNyYvi2l4Pxt6RJr792+w=
@@ -42,6 +63,7 @@ github.com/go-resty/resty/v2 v2.17.1/go.mod h1:kCKZ3wWmwJaNc7S29BRtUhJwy7iqmn+2m
 github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
 github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
 github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
+github.com/godbus/dbus/v5 v5.0.4/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/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
@@ -63,6 +85,8 @@ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
 github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
+github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
@@ -72,6 +96,8 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/grbit/go-json v0.11.0 h1:bAbyMdYrYl/OjYsSqLH99N2DyQ291mHy726Mx+sYrnc=
 github.com/grbit/go-json v0.11.0/go.mod h1:IYpHsdybQ386+6g3VE6AXQ3uTGa5mquBme5/ZWmtzek=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
@@ -91,8 +117,23 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
 github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
+github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
+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/mymmrac/telego v1.6.0 h1:Zc8rgyHozvd/7ZgyrigyHdAF9koHYMfilYfyB6wlFC0=
 github.com/mymmrac/telego v1.6.0/go.mod h1:xt6ZWA8zi8KmuzryE1ImEdl9JSwjHNpM4yhC7D8hU4Y=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -105,13 +146,27 @@ 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/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=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/rivo/tview v0.42.0 h1:b/ftp+RxtDsHSaynXTbJb+/n/BxDEi+W3UfF5jILK6c=
+github.com/rivo/tview v0.42.0/go.mod h1:cSfIYfhpSGCjp3r/ECJb+GKS7cGJnqV8vfjQPwoXyfY=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
 github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
 github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
+github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
+github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+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=
 github.com/slack-go/slack v0.17.3/go.mod h1:X+UqOufi3LYQHDnMG1vxf0J8asC6+WllXrVrhl8/Prk=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
@@ -153,11 +208,19 @@ github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZy
 github.com/valyala/fasthttp v1.69.0/go.mod h1:4wA4PfAraPlAsJ5jMSqCE2ug5tqUPwKXxVj8oNECGcw=
 github.com/valyala/fastjson v1.6.7 h1:ZE4tRy0CIkh+qDc5McjatheGX2czdn8slQjomexVpBM=
 github.com/valyala/fastjson v1.6.7/go.mod h1:CLCAqky6SMuOcxStkYQvblddUtoRxhYMGLrsQns1aXY=
+github.com/vektah/gqlparser/v2 v2.5.27 h1:RHPD3JOplpk5mP5JGX8RKZkt2/Vwj/PZv0HxTdwFp0s=
+github.com/vektah/gqlparser/v2 v2.5.27/go.mod h1:D1/VCZtV3LPnQrcPBeR/q5jkSQIPti0uYCP/RI0gIeo=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 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/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=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
@@ -171,10 +234,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.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
 golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+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/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/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=
@@ -217,8 +284,11 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
@@ -227,6 +297,8 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0=
+golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
+golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -234,8 +306,10 @@ golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
-golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
+golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
@@ -243,6 +317,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/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=
@@ -255,6 +331,8 @@ google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzi
 google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
@@ -269,3 +347,33 @@ 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=
+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=
+modernc.org/ccgo/v4 v4.30.1/go.mod h1:bIOeI1JL54Utlxn+LwrFyjCx2n2RDiYEaJVSrgdrRfM=
+modernc.org/fileutil v1.3.40 h1:ZGMswMNc9JOCrcrakF1HrvmergNLAmxOPjizirpfqBA=
+modernc.org/fileutil v1.3.40/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.1 h1:k8T3gkXWY9sEiytKhcgyiZ2L0DTyCQ/nvX+LoCljoRE=
+modernc.org/gc/v3 v3.1.1/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.67.6 h1:eVOQvpModVLKOdT+LvBPjdQqfrZq+pC39BygcT+E7OI=
+modernc.org/libc v1.67.6/go.mod h1:JAhxUVlolfYDErnwiqaLvUqc8nfb2r6S6slAgZOnaiE=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
+modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
+modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.46.1 h1:eFJ2ShBLIEnUWlLy12raN0Z1plqmFX9Qe3rjQTKt6sU=
+modernc.org/sqlite v1.46.1/go.mod h1:CzbrU2lSB1DKUusvwGz7rqEKIq+NUd8GWuBBZDs9/nA=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=
@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strings"
 	"sync"
 	"time"
@@ -249,10 +250,8 @@ func (cb *ContextBuilder) sourceFilesChangedLocked() bool {
 	}

 	// Check tracked source files (bootstrap + memory).
-	for _, p := range cb.sourcePaths() {
-		if cb.fileChangedSince(p) {
-			return true
-		}
+	if slices.ContainsFunc(cb.sourcePaths(), cb.fileChangedSince) {
+		return true
 	}

 	// --- Skills directory (handled separately from sourcePaths) ---
@@ -404,11 +404,11 @@ func TestConcurrentBuildSystemPromptWithCache(t *testing.T) {
 	var wg sync.WaitGroup
 	errs := make(chan string, goroutines*iterations)

-	for g := 0; g < goroutines; g++ {
+	for g := range goroutines {
 		wg.Add(1)
 		go func(id int) {
 			defer wg.Done()
-			for i := 0; i < iterations; i++ {
+			for i := range iterations {
 				result := cb.BuildSystemPromptWithCache()
 				if result == "" {
 					errs <- "empty prompt returned"
@@ -1,8 +1,11 @@
 package agent

 import (
+	"fmt"
+	"log"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"

 	"github.com/sipeed/picoclaw/pkg/config"
@@ -47,13 +50,24 @@ func NewAgentInstance(
 	fallbacks := resolveAgentFallbacks(agentCfg, defaults)

 	restrict := defaults.RestrictToWorkspace
+	readRestrict := restrict && !defaults.AllowReadOutsideWorkspace
+
+	// Compile path whitelist patterns from config.
+	allowReadPaths := compilePatterns(cfg.Tools.AllowReadPaths)
+	allowWritePaths := compilePatterns(cfg.Tools.AllowWritePaths)
+
 	toolsRegistry := tools.NewToolRegistry()
-	toolsRegistry.Register(tools.NewReadFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewListDirTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewExecToolWithConfig(workspace, restrict, cfg))
-	toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict))
-	toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict))
+	toolsRegistry.Register(tools.NewReadFileTool(workspace, readRestrict, allowReadPaths))
+	toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths))
+	toolsRegistry.Register(tools.NewListDirTool(workspace, readRestrict, allowReadPaths))
+	execTool, err := tools.NewExecToolWithConfig(workspace, restrict, cfg)
+	if err != nil {
+		log.Fatalf("Critical error: unable to initialize exec tool: %v", err)
+	}
+	toolsRegistry.Register(execTool)
+
+	toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict, allowWritePaths))
+	toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths))

 	sessionsDir := filepath.Join(workspace, "sessions")
 	sessionsManager := session.NewSessionManager(sessionsDir)
@@ -92,7 +106,47 @@ func NewAgentInstance(
 		Primary:   model,
 		Fallbacks: fallbacks,
 	}
-	candidates := providers.ResolveCandidates(modelCfg, defaults.Provider)
+	resolveFromModelList := 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
+		}
+
+		raw = strings.TrimSpace(raw)
+		if raw == "" {
+			return "", false
+		}
+
+		if cfg != nil {
+			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
+	}
+
+	candidates := providers.ResolveCandidatesWithLookup(modelCfg, defaults.Provider, resolveFromModelList)

 	return &AgentInstance{
 		ID:             agentID,
@@ -143,6 +197,19 @@ func resolveAgentFallbacks(agentCfg *config.AgentConfig, defaults *config.AgentD
 	return defaults.ModelFallbacks
 }

+func compilePatterns(patterns []string) []*regexp.Regexp {
+	compiled := make([]*regexp.Regexp, 0, len(patterns))
+	for _, p := range patterns {
+		re, err := regexp.Compile(p)
+		if err != nil {
+			fmt.Printf("Warning: invalid path pattern %q: %v\n", p, err)
+			continue
+		}
+		compiled = append(compiled, re)
+	}
+	return compiled
+}
+
 func expandHome(path string) string {
 	if path == "" {
 		return path
@@ -93,3 +93,77 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 		t.Fatalf("Temperature = %f, want %f", agent.Temperature, 0.7)
 	}
 }
+
+func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace: tmpDir,
+				Model:     "step-3.5-flash",
+			},
+		},
+		ModelList: []config.ModelConfig{
+			{
+				ModelName: "step-3.5-flash",
+				Model:     "openrouter/stepfun/step-3.5-flash:free",
+				APIBase:   "https://openrouter.ai/api/v1",
+			},
+		},
+	}
+
+	provider := &mockProvider{}
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+
+	if len(agent.Candidates) != 1 {
+		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+	}
+	if agent.Candidates[0].Provider != "openrouter" {
+		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openrouter")
+	}
+	if agent.Candidates[0].Model != "stepfun/step-3.5-flash:free" {
+		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "stepfun/step-3.5-flash:free")
+	}
+}
+
+func TestNewAgentInstance_ResolveCandidatesFromModelListAliasWithoutProtocol(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace: tmpDir,
+				Model:     "glm-5",
+			},
+		},
+		ModelList: []config.ModelConfig{
+			{
+				ModelName: "glm-5",
+				Model:     "glm-5",
+				APIBase:   "https://api.z.ai/api/coding/paas/v4",
+			},
+		},
+	}
+
+	provider := &mockProvider{}
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+
+	if len(agent.Candidates) != 1 {
+		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+	}
+	if agent.Candidates[0].Provider != "openai" {
+		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openai")
+	}
+	if agent.Candidates[0].Model != "glm-5" {
+		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "glm-5")
+	}
+}
@@ -9,7 +9,9 @@ package agent
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"path/filepath"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -21,6 +23,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/routing"
 	"github.com/sipeed/picoclaw/pkg/skills"
@@ -38,6 +41,7 @@ type AgentLoop struct {
 	summarizing    sync.Map
 	fallback       *providers.FallbackChain
 	channelManager *channels.Manager
+	mediaStore     media.MediaStore
 }

 // processOptions configures how a message is processed
@@ -95,7 +99,7 @@ func registerSharedTools(
 		}

 		// Web tools
-		if searchTool := tools.NewWebSearchTool(tools.WebSearchToolOptions{
+		searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
 			BraveAPIKey:          cfg.Tools.Web.Brave.APIKey,
 			BraveMaxResults:      cfg.Tools.Web.Brave.MaxResults,
 			BraveEnabled:         cfg.Tools.Web.Brave.Enabled,
@@ -109,10 +113,18 @@ func registerSharedTools(
 			PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
 			PerplexityEnabled:    cfg.Tools.Web.Perplexity.Enabled,
 			Proxy:                cfg.Tools.Web.Proxy,
-		}); searchTool != nil {
+		})
+		if err != nil {
+			logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
+		} else if searchTool != nil {
 			agent.Tools.Register(searchTool)
 		}
-		agent.Tools.Register(tools.NewWebFetchToolWithProxy(50000, cfg.Tools.Web.Proxy))
+		fetchTool, err := tools.NewWebFetchToolWithProxy(50000, cfg.Tools.Web.Proxy, cfg.Tools.Web.FetchLimitBytes)
+		if err != nil {
+			logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+		} else {
+			agent.Tools.Register(fetchTool)
+		}

 		// Hardware tools (I2C, SPI) - Linux only, returns error on other platforms
 		agent.Tools.Register(tools.NewI2CTool())
@@ -121,12 +133,13 @@ func registerSharedTools(
 		// Message tool
 		messageTool := tools.NewMessageTool()
 		messageTool.SetSendCallback(func(channel, chatID, content string) error {
-			msgBus.PublishOutbound(bus.OutboundMessage{
+			pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer pubCancel()
+			return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
 				Channel: channel,
 				ChatID:  chatID,
 				Content: content,
 			})
-			return nil
 		})
 		agent.Tools.Register(messageTool)

@@ -167,33 +180,61 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				continue
 			}

-			response, err := al.processMessage(ctx, msg)
-			if err != nil {
-				response = fmt.Sprintf("Error processing message: %v", err)
-			}
+			// Process message
+			func() {
+				// TODO: Re-enable media cleanup after inbound media is properly consumed by the agent.
+				// Currently disabled because files are deleted before the LLM can access their content.
+				// defer func() {
+				// 	if al.mediaStore != nil && msg.MediaScope != "" {
+				// 		if releaseErr := al.mediaStore.ReleaseAll(msg.MediaScope); releaseErr != nil {
+				// 			logger.WarnCF("agent", "Failed to release media", map[string]any{
+				// 				"scope": msg.MediaScope,
+				// 				"error": releaseErr.Error(),
+				// 			})
+				// 		}
+				// 	}
+				// }()

-			if response != "" {
-				// Check if the message tool already sent a response during this round.
-				// If so, skip publishing to avoid duplicate messages to the user.
-				// Use default agent's tools to check (message tool is shared).
-				alreadySent := false
-				defaultAgent := al.registry.GetDefaultAgent()
-				if defaultAgent != nil {
-					if tool, ok := defaultAgent.Tools.Get("message"); ok {
-						if mt, ok := tool.(*tools.MessageTool); ok {
-							alreadySent = mt.HasSentInRound()
+				response, err := al.processMessage(ctx, msg)
+				if err != nil {
+					response = fmt.Sprintf("Error processing message: %v", err)
+				}
+
+				if response != "" {
+					// Check if the message tool already sent a response during this round.
+					// If so, skip publishing to avoid duplicate messages to the user.
+					// Use default agent's tools to check (message tool is shared).
+					alreadySent := false
+					defaultAgent := al.registry.GetDefaultAgent()
+					if defaultAgent != nil {
+						if tool, ok := defaultAgent.Tools.Get("message"); ok {
+							if mt, ok := tool.(*tools.MessageTool); ok {
+								alreadySent = mt.HasSentInRound()
+							}
 						}
 					}
-				}

-				if !alreadySent {
-					al.bus.PublishOutbound(bus.OutboundMessage{
-						Channel: msg.Channel,
-						ChatID:  msg.ChatID,
-						Content: response,
-					})
+					if !alreadySent {
+						al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+							Channel: msg.Channel,
+							ChatID:  msg.ChatID,
+							Content: response,
+						})
+						logger.InfoCF("agent", "Published outbound response",
+							map[string]any{
+								"channel":     msg.Channel,
+								"chat_id":     msg.ChatID,
+								"content_len": len(response),
+							})
+					} else {
+						logger.DebugCF(
+							"agent",
+							"Skipped outbound (message tool already sent)",
+							map[string]any{"channel": msg.Channel},
+						)
+					}
 				}
-			}
+			}()
 		}
 	}

@@ -216,6 +257,41 @@ func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
 	al.channelManager = cm
 }

+// SetMediaStore injects a MediaStore for media lifecycle management.
+func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
+	al.mediaStore = s
+}
+
+// inferMediaType determines the media type ("image", "audio", "video", "file")
+// from a filename and MIME content type.
+func inferMediaType(filename, contentType string) string {
+	ct := strings.ToLower(contentType)
+	fn := strings.ToLower(filename)
+
+	if strings.HasPrefix(ct, "image/") {
+		return "image"
+	}
+	if strings.HasPrefix(ct, "audio/") || ct == "application/ogg" {
+		return "audio"
+	}
+	if strings.HasPrefix(ct, "video/") {
+		return "video"
+	}
+
+	// Fallback: infer from extension
+	ext := filepath.Ext(fn)
+	switch ext {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus":
+		return "audio"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	}
+
+	return "file"
+}
+
 // RecordLastChannel records the last active channel for this workspace.
 // This uses the atomic state save mechanism to prevent data loss on crash.
 func (al *AgentLoop) RecordLastChannel(channel string) error {
@@ -257,6 +333,9 @@ func (al *AgentLoop) ProcessDirectWithChannel(
 // Each heartbeat is independent and doesn't accumulate context.
 func (al *AgentLoop) ProcessHeartbeat(ctx context.Context, content, channel, chatID string) (string, error) {
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for heartbeat")
+	}
 	return al.runAgentLoop(ctx, agent, processOptions{
 		SessionKey:      "heartbeat",
 		Channel:         channel,
@@ -309,6 +388,16 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 	if !ok {
 		agent = al.registry.GetDefaultAgent()
 	}
+	if agent == nil {
+		return "", fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
+	}
+
+	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
+	if tool, ok := agent.Tools.Get("message"); ok {
+		if mt, ok := tool.(tools.ContextualTool); ok {
+			mt.SetContext(msg.Channel, msg.ChatID)
+		}
+	}

 	// Use routed session key, but honor pre-set agent-scoped keys (for ProcessDirect/cron)
 	sessionKey := route.SessionKey
@@ -375,6 +464,9 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe

 	// Use default agent for system messages
 	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		return "", fmt.Errorf("no default agent for system message")
+	}

 	// Use the origin session for context
 	sessionKey := routing.BuildAgentMainSessionKey(agent.ID)
@@ -450,7 +542,7 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt

 	// 8. Optional: send response via bus
 	if opts.SendResponse {
-		al.bus.PublishOutbound(bus.OutboundMessage{
+		al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 			Channel: opts.Channel,
 			ChatID:  opts.ChatID,
 			Content: finalContent,
@@ -470,6 +562,59 @@ func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opt
 	return finalContent, nil
 }

+func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
+	if al.channelManager == nil {
+		return ""
+	}
+	if ch, ok := al.channelManager.GetChannel(channelName); ok {
+		return ch.ReasoningChannelID()
+	}
+	return ""
+}
+
+func (al *AgentLoop) handleReasoning(ctx context.Context, reasoningContent, channelName, channelID string) {
+	if reasoningContent == "" || channelName == "" || channelID == "" {
+		return
+	}
+
+	// Check context cancellation before attempting to publish,
+	// since PublishOutbound's select may race between send and ctx.Done().
+	if ctx.Err() != nil {
+		return
+	}
+
+	// Use a short timeout so the goroutine does not block indefinitely when
+	// the outbound bus is full.  Reasoning output is best-effort; dropping it
+	// is acceptable to avoid goroutine accumulation.
+	pubCtx, pubCancel := context.WithTimeout(ctx, 5*time.Second)
+	defer pubCancel()
+
+	if err := al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Channel: channelName,
+		ChatID:  channelID,
+		Content: reasoningContent,
+	}); err != nil {
+		// Treat context.DeadlineExceeded / context.Canceled as expected
+		// (bus full under load, or parent canceled).  Check the error
+		// itself rather than ctx.Err(), because pubCtx may time out
+		// (5 s) while the parent ctx is still active.
+		// Also treat ErrBusClosed as expected — it occurs during normal
+		// shutdown when the bus is closed before all goroutines finish.
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) ||
+			errors.Is(err, bus.ErrBusClosed) {
+			logger.DebugCF("agent", "Reasoning publish skipped (timeout/cancel)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		} else {
+			logger.WarnCF("agent", "Failed to publish reasoning (best-effort)", map[string]any{
+				"channel": channelName,
+				"error":   err.Error(),
+			})
+		}
+	}
+}
+
 // runLLMIteration executes the LLM call loop with tool handling.
 func (al *AgentLoop) runLLMIteration(
 	ctx context.Context,
@@ -555,10 +700,35 @@ func (al *AgentLoop) runLLMIteration(
 			}

 			errMsg := strings.ToLower(err.Error())
-			isContextError := strings.Contains(errMsg, "token") ||
-				strings.Contains(errMsg, "context") ||
+
+			// Check if this is a network/HTTP timeout — not a context window error.
+			isTimeoutError := errors.Is(err, context.DeadlineExceeded) ||
+				strings.Contains(errMsg, "deadline exceeded") ||
+				strings.Contains(errMsg, "client.timeout") ||
+				strings.Contains(errMsg, "timed out") ||
+				strings.Contains(errMsg, "timeout exceeded")
+
+			// Detect real context window / token limit errors, excluding network timeouts.
+			isContextError := !isTimeoutError && (strings.Contains(errMsg, "context_length_exceeded") ||
+				strings.Contains(errMsg, "context window") ||
+				strings.Contains(errMsg, "maximum context length") ||
+				strings.Contains(errMsg, "token limit") ||
+				strings.Contains(errMsg, "too many tokens") ||
+				strings.Contains(errMsg, "max_tokens") ||
 				strings.Contains(errMsg, "invalidparameter") ||
-				strings.Contains(errMsg, "length")
+				strings.Contains(errMsg, "prompt is too long") ||
+				strings.Contains(errMsg, "request too large"))
+
+			if isTimeoutError && retry < maxRetries {
+				backoff := time.Duration(retry+1) * 5 * time.Second
+				logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
+					"error":   err.Error(),
+					"retry":   retry,
+					"backoff": backoff.String(),
+				})
+				time.Sleep(backoff)
+				continue
+			}

 			if isContextError && retry < maxRetries {
 				logger.WarnCF("agent", "Context window error detected, attempting compression", map[string]any{
@@ -567,7 +737,7 @@ func (al *AgentLoop) runLLMIteration(
 				})

 				if retry == 0 && !constants.IsInternalChannel(opts.Channel) {
-					al.bus.PublishOutbound(bus.OutboundMessage{
+					al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 						Channel: opts.Channel,
 						ChatID:  opts.ChatID,
 						Content: "Context window exceeded. Compressing history and retrying...",
@@ -596,6 +766,18 @@ func (al *AgentLoop) runLLMIteration(
 			return "", iteration, fmt.Errorf("LLM call failed after retries: %w", err)
 		}

+		go al.handleReasoning(ctx, response.Reasoning, opts.Channel, al.targetReasoningChannelID(opts.Channel))
+
+		logger.DebugCF("agent", "LLM response",
+			map[string]any{
+				"agent_id":       agent.ID,
+				"iteration":      iteration,
+				"content_chars":  len(response.Content),
+				"tool_calls":     len(response.ToolCalls),
+				"reasoning":      response.Reasoning,
+				"target_channel": al.targetReasoningChannelID(opts.Channel),
+				"channel":        opts.Channel,
+			})
 		// Check if no tool calls - we're done
 		if len(response.ToolCalls) == 0 {
 			finalContent = response.Content
@@ -697,7 +879,7 @@ func (al *AgentLoop) runLLMIteration(

 			// Send ForUser content to user immediately if not Silent
 			if !toolResult.Silent && toolResult.ForUser != "" && opts.SendResponse {
-				al.bus.PublishOutbound(bus.OutboundMessage{
+				al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 					Channel: opts.Channel,
 					ChatID:  opts.ChatID,
 					Content: toolResult.ForUser,
@@ -709,6 +891,28 @@ func (al *AgentLoop) runLLMIteration(
 					})
 			}

+			// If tool returned media refs, publish them as outbound media
+			if len(toolResult.Media) > 0 && opts.SendResponse {
+				parts := make([]bus.MediaPart, 0, len(toolResult.Media))
+				for _, ref := range toolResult.Media {
+					part := bus.MediaPart{Ref: ref}
+					// Populate metadata from MediaStore when available
+					if al.mediaStore != nil {
+						if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil {
+							part.Filename = meta.Filename
+							part.ContentType = meta.ContentType
+							part.Type = inferMediaType(meta.Filename, meta.ContentType)
+						}
+					}
+					parts = append(parts, part)
+				}
+				al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{
+					Channel: opts.Channel,
+					ChatID:  opts.ChatID,
+					Parts:   parts,
+				})
+			}
+
 			// Determine content for LLM based on tool result
 			contentForLLM := toolResult.ForLLM
 			if contentForLLM == "" && toolResult.Err != nil {
@@ -1121,21 +1325,20 @@ func (al *AgentLoop) handleCommand(ctx context.Context, msg bus.InboundMessage)
 	return "", false
 }

-// extractPeer extracts the routing peer from inbound message metadata.
+// extractPeer extracts the routing peer from the inbound message's structured Peer field.
 func extractPeer(msg bus.InboundMessage) *routing.RoutePeer {
-	peerKind := msg.Metadata["peer_kind"]
-	if peerKind == "" {
+	if msg.Peer.Kind == "" {
 		return nil
 	}
-	peerID := msg.Metadata["peer_id"]
+	peerID := msg.Peer.ID
 	if peerID == "" {
-		if peerKind == "direct" {
+		if msg.Peer.Kind == "direct" {
 			peerID = msg.SenderID
 		} else {
 			peerID = msg.ChatID
 		}
 	}
-	return &routing.RoutePeer{Kind: peerKind, ID: peerID}
+	return &routing.RoutePeer{Kind: msg.Peer.Kind, ID: peerID}
 }

 // extractParentPeer extracts the parent peer (reply-to) from inbound message metadata.
@@ -5,15 +5,28 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"slices"
 	"testing"
 	"time"

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

+type fakeChannel struct{ id string }
+
+func (f *fakeChannel) Name() string                                            { return "fake" }
+func (f *fakeChannel) Start(ctx context.Context) error                         { return nil }
+func (f *fakeChannel) Stop(ctx context.Context) error                          { return nil }
+func (f *fakeChannel) Send(ctx context.Context, msg bus.OutboundMessage) error { return nil }
+func (f *fakeChannel) IsRunning() bool                                         { return true }
+func (f *fakeChannel) IsAllowed(string) bool                                   { return true }
+func (f *fakeChannel) IsAllowedSender(sender bus.SenderInfo) bool              { return true }
+func (f *fakeChannel) ReasoningChannelID() string                              { return f.id }
+
 func TestRecordLastChannel(t *testing.T) {
 	// Create temp workspace
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -175,13 +188,7 @@ func TestToolRegistry_ToolRegistration(t *testing.T) {
 	toolsList := toolsInfo["names"].([]string)

 	// Check that our custom tool name is in the list
-	found := false
-	for _, name := range toolsList {
-		if name == "mock_custom" {
-			found = true
-			break
-		}
-	}
+	found := slices.Contains(toolsList, "mock_custom")
 	if !found {
 		t.Error("Expected custom tool to be registered")
 	}
@@ -250,13 +257,7 @@ func TestToolRegistry_GetDefinitions(t *testing.T) {
 	toolsList := toolsInfo["names"].([]string)

 	// Check that our custom tool name is in the list
-	found := false
-	for _, name := range toolsList {
-		if name == "mock_custom" {
-			found = true
-			break
-		}
-	}
+	found := slices.Contains(toolsList, "mock_custom")
 	if !found {
 		t.Error("Expected custom tool to be registered")
 	}
@@ -631,3 +632,211 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
 		t.Errorf("Expected history to be compressed (len < 8), got %d", len(finalHistory))
 	}
 }
+
+func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				Model:             "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), &mockProvider{})
+	chManager, err := channels.NewManager(&config.Config{}, bus.NewMessageBus(), nil)
+	if err != nil {
+		t.Fatalf("Failed to create channel manager: %v", err)
+	}
+	for name, id := range map[string]string{
+		"whatsapp":  "rid-whatsapp",
+		"telegram":  "rid-telegram",
+		"feishu":    "rid-feishu",
+		"discord":   "rid-discord",
+		"maixcam":   "rid-maixcam",
+		"qq":        "rid-qq",
+		"dingtalk":  "rid-dingtalk",
+		"slack":     "rid-slack",
+		"line":      "rid-line",
+		"onebot":    "rid-onebot",
+		"wecom":     "rid-wecom",
+		"wecom_app": "rid-wecom-app",
+	} {
+		chManager.RegisterChannel(name, &fakeChannel{id: id})
+	}
+	al.SetChannelManager(chManager)
+	tests := []struct {
+		channel string
+		wantID  string
+	}{
+		{channel: "whatsapp", wantID: "rid-whatsapp"},
+		{channel: "telegram", wantID: "rid-telegram"},
+		{channel: "feishu", wantID: "rid-feishu"},
+		{channel: "discord", wantID: "rid-discord"},
+		{channel: "maixcam", wantID: "rid-maixcam"},
+		{channel: "qq", wantID: "rid-qq"},
+		{channel: "dingtalk", wantID: "rid-dingtalk"},
+		{channel: "slack", wantID: "rid-slack"},
+		{channel: "line", wantID: "rid-line"},
+		{channel: "onebot", wantID: "rid-onebot"},
+		{channel: "wecom", wantID: "rid-wecom"},
+		{channel: "wecom_app", wantID: "rid-wecom-app"},
+		{channel: "unknown", wantID: ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.channel, func(t *testing.T) {
+			got := al.targetReasoningChannelID(tt.channel)
+			if got != tt.wantID {
+				t.Fatalf("targetReasoningChannelID(%q) = %q, want %q", tt.channel, got, tt.wantID)
+			}
+		})
+	}
+}
+
+func TestHandleReasoning(t *testing.T) {
+	newLoop := func(t *testing.T) (*AgentLoop, *bus.MessageBus) {
+		t.Helper()
+		tmpDir, err := os.MkdirTemp("", "agent-test-*")
+		if err != nil {
+			t.Fatalf("Failed to create temp dir: %v", err)
+		}
+		t.Cleanup(func() { _ = os.RemoveAll(tmpDir) })
+		cfg := &config.Config{
+			Agents: config.AgentsConfig{
+				Defaults: config.AgentDefaults{
+					Workspace:         tmpDir,
+					Model:             "test-model",
+					MaxTokens:         4096,
+					MaxToolIterations: 10,
+				},
+			},
+		}
+		msgBus := bus.NewMessageBus()
+		return NewAgentLoop(cfg, msgBus, &mockProvider{}), msgBus
+	}
+
+	t.Run("skips when any required field is empty", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		al.handleReasoning(context.Background(), "reasoning", "telegram", "")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+		defer cancel()
+		if msg, ok := msgBus.SubscribeOutbound(ctx); ok {
+			t.Fatalf("expected no outbound message, got %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for non telegram", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		al.handleReasoning(context.Background(), "hello reasoning", "slack", "channel-1")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if !ok {
+			t.Fatal("expected an outbound message")
+		}
+		if msg.Channel != "slack" || msg.ChatID != "channel-1" || msg.Content != "hello reasoning" {
+			t.Fatalf("unexpected outbound message: %+v", msg)
+		}
+	})
+
+	t.Run("publishes one message for telegram", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		reasoning := "hello telegram reasoning"
+		al.handleReasoning(context.Background(), reasoning, "telegram", "tg-chat")
+
+		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if !ok {
+			t.Fatal("expected outbound message")
+		}
+
+		if msg.Channel != "telegram" {
+			t.Fatalf("expected telegram channel message, got %+v", msg)
+		}
+		if msg.ChatID != "tg-chat" {
+			t.Fatalf("expected chatID tg-chat, got %+v", msg)
+		}
+		if msg.Content != reasoning {
+			t.Fatalf("content mismatch: got %q want %q", msg.Content, reasoning)
+		}
+	})
+	t.Run("expired ctx", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+		reasoning := "hello telegram reasoning"
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		al.handleReasoning(ctx, reasoning, "telegram", "tg-chat")
+
+		ctx, cancel = context.WithTimeout(context.Background(), 200*time.Millisecond)
+		defer cancel()
+		msg, ok := msgBus.SubscribeOutbound(ctx)
+		if ok {
+			t.Fatalf("expected no outbound message, got %+v", msg)
+		}
+	})
+
+	t.Run("returns promptly when bus is full", func(t *testing.T) {
+		al, msgBus := newLoop(t)
+
+		// Fill the outbound bus buffer until a publish would block.
+		// Use a short timeout to detect when the buffer is full,
+		// rather than hardcoding the buffer size.
+		for i := 0; ; i++ {
+			fillCtx, fillCancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+			err := msgBus.PublishOutbound(fillCtx, bus.OutboundMessage{
+				Channel: "filler",
+				ChatID:  "filler",
+				Content: fmt.Sprintf("filler-%d", i),
+			})
+			fillCancel()
+			if err != nil {
+				// Buffer is full (timed out trying to send).
+				break
+			}
+		}
+
+		// Use a short-deadline parent context to bound the test.
+		ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+		defer cancel()
+
+		start := time.Now()
+		al.handleReasoning(ctx, "should timeout", "slack", "channel-full")
+		elapsed := time.Since(start)
+
+		// handleReasoning uses a 5s internal timeout, but the parent ctx
+		// expires in 500ms. It should return within ~500ms, not 5s.
+		if elapsed > 2*time.Second {
+			t.Fatalf("handleReasoning blocked too long (%v); expected prompt return", elapsed)
+		}
+
+		// Drain the bus and verify the reasoning message was NOT published
+		// (it should have been dropped due to timeout).
+		drainCtx, drainCancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+		defer drainCancel()
+		foundReasoning := false
+		for {
+			msg, ok := msgBus.SubscribeOutbound(drainCtx)
+			if !ok {
+				break
+			}
+			if msg.Content == "should timeout" {
+				foundReasoning = true
+			}
+		}
+		if foundReasoning {
+			t.Fatal("expected reasoning message to be dropped when bus is full, but it was published")
+		}
+	})
+}
@@ -111,7 +111,7 @@ func (ms *MemoryStore) GetRecentDailyNotes(days int) string {
 	var sb strings.Builder
 	first := true

-	for i := 0; i < days; i++ {
+	for i := range days {
 		date := time.Now().AddDate(0, 0, -i)
 		dateStr := date.Format("20060102") // YYYYMMDD
 		monthDir := dateStr[:6]            // YYYYMM
@@ -66,7 +66,8 @@ func decodeBase64(s string) string {
 	return string(data)
 }

-func generateState() (string, error) {
+// GenerateState generates a random state string for OAuth CSRF protection.
+func GenerateState() (string, error) {
 	buf := make([]byte, 32)
 	if _, err := rand.Read(buf); err != nil {
 		return "", err
@@ -80,7 +81,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		return nil, fmt.Errorf("generating PKCE: %w", err)
 	}

-	state, err := generateState()
+	state, err := GenerateState()
 	if err != nil {
 		return nil, fmt.Errorf("generating state: %w", err)
 	}
@@ -127,7 +128,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {

 	fmt.Printf("Open this URL to authenticate:\n\n%s\n\n", authURL)

-	if err := openBrowser(authURL); err != nil {
+	if err := OpenBrowser(authURL); err != nil {
 		fmt.Printf("Could not open browser automatically.\nPlease open this URL manually:\n\n%s\n\n", authURL)
 	}

@@ -153,7 +154,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		if result.err != nil {
 			return nil, result.err
 		}
-		return exchangeCodeForTokens(cfg, result.code, pkce.CodeVerifier, redirectURI)
+		return ExchangeCodeForTokens(cfg, result.code, pkce.CodeVerifier, redirectURI)
 	case manualInput := <-manualCh:
 		if manualInput == "" {
 			return nil, fmt.Errorf("manual input canceled")
@@ -169,7 +170,7 @@ func LoginBrowser(cfg OAuthProviderConfig) (*AuthCredential, error) {
 		if code == "" {
 			return nil, fmt.Errorf("could not find authorization code in input")
 		}
-		return exchangeCodeForTokens(cfg, code, pkce.CodeVerifier, redirectURI)
+		return ExchangeCodeForTokens(cfg, code, pkce.CodeVerifier, redirectURI)
 	case <-time.After(5 * time.Minute):
 		return nil, fmt.Errorf("authentication timed out after 5 minutes")
 	}
@@ -186,6 +187,59 @@ type deviceCodeResponse struct {
 	Interval     int
 }

+// DeviceCodeInfo holds the device code information returned by the OAuth provider.
+type DeviceCodeInfo struct {
+	DeviceAuthID string `json:"device_auth_id"`
+	UserCode     string `json:"user_code"`
+	VerifyURL    string `json:"verify_url"`
+	Interval     int    `json:"interval"`
+}
+
+// RequestDeviceCode requests a device code from the OAuth provider.
+// Returns the info needed for the user to authenticate in a browser.
+func RequestDeviceCode(cfg OAuthProviderConfig) (*DeviceCodeInfo, error) {
+	reqBody, _ := json.Marshal(map[string]string{
+		"client_id": cfg.ClientID,
+	})
+
+	resp, err := http.Post(
+		cfg.Issuer+"/api/accounts/deviceauth/usercode",
+		"application/json",
+		strings.NewReader(string(reqBody)),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("requesting device code: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("device code request failed: %s", string(body))
+	}
+
+	deviceResp, err := parseDeviceCodeResponse(body)
+	if err != nil {
+		return nil, fmt.Errorf("parsing device code response: %w", err)
+	}
+
+	if deviceResp.Interval < 1 {
+		deviceResp.Interval = 5
+	}
+
+	return &DeviceCodeInfo{
+		DeviceAuthID: deviceResp.DeviceAuthID,
+		UserCode:     deviceResp.UserCode,
+		VerifyURL:    cfg.Issuer + "/codex/device",
+		Interval:     deviceResp.Interval,
+	}, nil
+}
+
+// PollDeviceCodeOnce makes a single poll attempt to check if the user has authenticated.
+// Returns (credential, nil) on success, (nil, nil) if still pending, or (nil, err) on failure.
+func PollDeviceCodeOnce(cfg OAuthProviderConfig, deviceAuthID, userCode string) (*AuthCredential, error) {
+	return pollDeviceCode(cfg, deviceAuthID, userCode)
+}
+
 func parseDeviceCodeResponse(body []byte) (deviceCodeResponse, error) {
 	var raw struct {
 		DeviceAuthID string          `json:"device_auth_id"`
@@ -318,7 +372,7 @@ func pollDeviceCode(cfg OAuthProviderConfig, deviceAuthID, userCode string) (*Au
 	}

 	redirectURI := cfg.Issuer + "/deviceauth/callback"
-	return exchangeCodeForTokens(cfg, tokenResp.AuthorizationCode, tokenResp.CodeVerifier, redirectURI)
+	return ExchangeCodeForTokens(cfg, tokenResp.AuthorizationCode, tokenResp.CodeVerifier, redirectURI)
 }

 func RefreshAccessToken(cred *AuthCredential, cfg OAuthProviderConfig) (*AuthCredential, error) {
@@ -410,7 +464,8 @@ func buildAuthorizeURL(cfg OAuthProviderConfig, pkce PKCECodes, state, redirectU
 	return cfg.Issuer + "/oauth/authorize?" + params.Encode()
 }

-func exchangeCodeForTokens(cfg OAuthProviderConfig, code, codeVerifier, redirectURI string) (*AuthCredential, error) {
+// ExchangeCodeForTokens exchanges an authorization code for tokens.
+func ExchangeCodeForTokens(cfg OAuthProviderConfig, code, codeVerifier, redirectURI string) (*AuthCredential, error) {
 	data := url.Values{
 		"grant_type":    {"authorization_code"},
 		"code":          {code},
@@ -552,7 +607,8 @@ func base64URLDecode(s string) ([]byte, error) {
 	return base64.StdEncoding.DecodeString(s)
 }

-func openBrowser(url string) error {
+// OpenBrowser opens the given URL in the user's default browser.
+func OpenBrowser(url string) error {
 	switch runtime.GOOS {
 	case "darwin":
 		return exec.Command("open", url).Start()
@@ -219,9 +219,9 @@ func TestExchangeCodeForTokens(t *testing.T) {
 		Port:     1455,
 	}

-	cred, err := exchangeCodeForTokens(cfg, "test-code", "test-verifier", "http://localhost:1455/auth/callback")
+	cred, err := ExchangeCodeForTokens(cfg, "test-code", "test-verifier", "http://localhost:1455/auth/callback")
 	if err != nil {
-		t.Fatalf("exchangeCodeForTokens() error: %v", err)
+		t.Fatalf("ExchangeCodeForTokens() error: %v", err)
 	}

 	if cred.AccessToken != "mock-access-token" {
@@ -2,81 +2,156 @@ package bus

 import (
 	"context"
-	"sync"
+	"errors"
+	"sync/atomic"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
 )

+// ErrBusClosed is returned when publishing to a closed MessageBus.
+var ErrBusClosed = errors.New("message bus closed")
+
+const defaultBusBufferSize = 64
+
 type MessageBus struct {
-	inbound  chan InboundMessage
-	outbound chan OutboundMessage
-	handlers map[string]MessageHandler
-	closed   bool
-	mu       sync.RWMutex
+	inbound       chan InboundMessage
+	outbound      chan OutboundMessage
+	outboundMedia chan OutboundMediaMessage
+	done          chan struct{}
+	closed        atomic.Bool
 }

 func NewMessageBus() *MessageBus {
 	return &MessageBus{
-		inbound:  make(chan InboundMessage, 100),
-		outbound: make(chan OutboundMessage, 100),
-		handlers: make(map[string]MessageHandler),
+		inbound:       make(chan InboundMessage, defaultBusBufferSize),
+		outbound:      make(chan OutboundMessage, defaultBusBufferSize),
+		outboundMedia: make(chan OutboundMediaMessage, defaultBusBufferSize),
+		done:          make(chan struct{}),
 	}
 }

-func (mb *MessageBus) PublishInbound(msg InboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.inbound <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
 	}
-	mb.inbound <- msg
 }

 func (mb *MessageBus) ConsumeInbound(ctx context.Context) (InboundMessage, bool) {
 	select {
-	case msg := <-mb.inbound:
-		return msg, true
+	case msg, ok := <-mb.inbound:
+		return msg, ok
+	case <-mb.done:
+		return InboundMessage{}, false
 	case <-ctx.Done():
 		return InboundMessage{}, false
 	}
 }

-func (mb *MessageBus) PublishOutbound(msg OutboundMessage) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	if mb.closed {
-		return
+func (mb *MessageBus) PublishOutbound(ctx context.Context, msg OutboundMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.outbound <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
 	}
-	mb.outbound <- msg
 }

 func (mb *MessageBus) SubscribeOutbound(ctx context.Context) (OutboundMessage, bool) {
 	select {
-	case msg := <-mb.outbound:
-		return msg, true
+	case msg, ok := <-mb.outbound:
+		return msg, ok
+	case <-mb.done:
+		return OutboundMessage{}, false
 	case <-ctx.Done():
 		return OutboundMessage{}, false
 	}
 }

-func (mb *MessageBus) RegisterHandler(channel string, handler MessageHandler) {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	mb.handlers[channel] = handler
+func (mb *MessageBus) PublishOutboundMedia(ctx context.Context, msg OutboundMediaMessage) error {
+	if mb.closed.Load() {
+		return ErrBusClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	select {
+	case mb.outboundMedia <- msg:
+		return nil
+	case <-mb.done:
+		return ErrBusClosed
+	case <-ctx.Done():
+		return ctx.Err()
+	}
 }

-func (mb *MessageBus) GetHandler(channel string) (MessageHandler, bool) {
-	mb.mu.RLock()
-	defer mb.mu.RUnlock()
-	handler, ok := mb.handlers[channel]
-	return handler, ok
+func (mb *MessageBus) SubscribeOutboundMedia(ctx context.Context) (OutboundMediaMessage, bool) {
+	select {
+	case msg, ok := <-mb.outboundMedia:
+		return msg, ok
+	case <-mb.done:
+		return OutboundMediaMessage{}, false
+	case <-ctx.Done():
+		return OutboundMediaMessage{}, false
+	}
 }

 func (mb *MessageBus) Close() {
-	mb.mu.Lock()
-	defer mb.mu.Unlock()
-	if mb.closed {
-		return
+	if mb.closed.CompareAndSwap(false, true) {
+		close(mb.done)
+
+		// Drain buffered channels so messages aren't silently lost.
+		// Channels are NOT closed to avoid send-on-closed panics from concurrent publishers.
+		drained := 0
+		for {
+			select {
+			case <-mb.inbound:
+				drained++
+			default:
+				goto doneInbound
+			}
+		}
+	doneInbound:
+		for {
+			select {
+			case <-mb.outbound:
+				drained++
+			default:
+				goto doneOutbound
+			}
+		}
+	doneOutbound:
+		for {
+			select {
+			case <-mb.outboundMedia:
+				drained++
+			default:
+				goto doneMedia
+			}
+		}
+	doneMedia:
+		if drained > 0 {
+			logger.DebugCF("bus", "Drained buffered messages during close", map[string]any{
+				"count": drained,
+			})
+		}
 	}
-	mb.closed = true
-	close(mb.inbound)
-	close(mb.outbound)
 }
@@ -0,0 +1,229 @@
+package bus
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestPublishConsume(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := InboundMessage{
+		Channel:  "test",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+	}
+
+	if err := mb.PublishInbound(ctx, msg); err != nil {
+		t.Fatalf("PublishInbound failed: %v", err)
+	}
+
+	got, ok := mb.ConsumeInbound(ctx)
+	if !ok {
+		t.Fatal("ConsumeInbound returned ok=false")
+	}
+	if got.Content != "hello" {
+		t.Fatalf("expected content 'hello', got %q", got.Content)
+	}
+	if got.Channel != "test" {
+		t.Fatalf("expected channel 'test', got %q", got.Channel)
+	}
+}
+
+func TestPublishOutboundSubscribe(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	msg := OutboundMessage{
+		Channel: "telegram",
+		ChatID:  "123",
+		Content: "world",
+	}
+
+	if err := mb.PublishOutbound(ctx, msg); err != nil {
+		t.Fatalf("PublishOutbound failed: %v", err)
+	}
+
+	got, ok := mb.SubscribeOutbound(ctx)
+	if !ok {
+		t.Fatal("SubscribeOutbound returned ok=false")
+	}
+	if got.Content != "world" {
+		t.Fatalf("expected content 'world', got %q", got.Content)
+	}
+}
+
+func TestPublishInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	// Fill the buffer
+	ctx := context.Background()
+	for i := range defaultBusBufferSize {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Now buffer is full; publish with a canceled context
+	cancelCtx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	err := mb.PublishInbound(cancelCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error from canceled context, got nil")
+	}
+	if err != context.Canceled {
+		t.Fatalf("expected context.Canceled, got %v", err)
+	}
+}
+
+func TestPublishInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestPublishOutbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	err := mb.PublishOutbound(context.Background(), OutboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed, got %v", err)
+	}
+}
+
+func TestConsumeInbound_ContextCancel(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when context is canceled")
+	}
+}
+
+func TestConsumeInbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	_, ok := mb.ConsumeInbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+func TestSubscribeOutbound_BusClosed(t *testing.T) {
+	mb := NewMessageBus()
+	mb.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	_, ok := mb.SubscribeOutbound(ctx)
+	if ok {
+		t.Fatal("expected ok=false when bus is closed")
+	}
+}
+
+func TestConcurrentPublishClose(t *testing.T) {
+	mb := NewMessageBus()
+	ctx := context.Background()
+
+	const numGoroutines = 100
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines + 1)
+
+	// Spawn many goroutines trying to publish
+	for range numGoroutines {
+		go func() {
+			defer wg.Done()
+			// Use a short timeout context so we don't block forever after close
+			publishCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
+			defer cancel()
+			// Errors are expected; we just must not panic or deadlock
+			_ = mb.PublishInbound(publishCtx, InboundMessage{Content: "concurrent"})
+		}()
+	}
+
+	// Close from another goroutine
+	go func() {
+		defer wg.Done()
+		time.Sleep(5 * time.Millisecond)
+		mb.Close()
+	}()
+
+	// Must complete without deadlock
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(5 * time.Second):
+		t.Fatal("test timed out - possible deadlock")
+	}
+}
+
+func TestPublishInbound_FullBuffer(t *testing.T) {
+	mb := NewMessageBus()
+	defer mb.Close()
+
+	ctx := context.Background()
+
+	// Fill the buffer
+	for i := range defaultBusBufferSize {
+		if err := mb.PublishInbound(ctx, InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
+
+	// Buffer is full; publish with short timeout
+	timeoutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond)
+	defer cancel()
+
+	err := mb.PublishInbound(timeoutCtx, InboundMessage{Content: "overflow"})
+	if err == nil {
+		t.Fatal("expected error when buffer is full and context times out")
+	}
+	if err != context.DeadlineExceeded {
+		t.Fatalf("expected context.DeadlineExceeded, got %v", err)
+	}
+}
+
+func TestCloseIdempotent(t *testing.T) {
+	mb := NewMessageBus()
+
+	// Multiple Close calls must not panic
+	mb.Close()
+	mb.Close()
+	mb.Close()
+
+	// After close, publish should return ErrBusClosed
+	err := mb.PublishInbound(context.Background(), InboundMessage{Content: "test"})
+	if err != ErrBusClosed {
+		t.Fatalf("expected ErrBusClosed after multiple closes, got %v", err)
+	}
+}
@@ -1,11 +1,30 @@
 package bus

+// Peer identifies the routing peer for a message (direct, group, channel, etc.)
+type Peer struct {
+	Kind string `json:"kind"` // "direct" | "group" | "channel" | ""
+	ID   string `json:"id"`
+}
+
+// SenderInfo provides structured sender identity information.
+type SenderInfo struct {
+	Platform    string `json:"platform,omitempty"`     // "telegram", "discord", "slack", ...
+	PlatformID  string `json:"platform_id,omitempty"`  // raw platform ID, e.g. "123456"
+	CanonicalID string `json:"canonical_id,omitempty"` // "platform:id" format
+	Username    string `json:"username,omitempty"`     // username (e.g. @alice)
+	DisplayName string `json:"display_name,omitempty"` // display name
+}
+
 type InboundMessage struct {
 	Channel    string            `json:"channel"`
 	SenderID   string            `json:"sender_id"`
+	Sender     SenderInfo        `json:"sender"`
 	ChatID     string            `json:"chat_id"`
 	Content    string            `json:"content"`
 	Media      []string          `json:"media,omitempty"`
+	Peer       Peer              `json:"peer"`                  // routing peer
+	MessageID  string            `json:"message_id,omitempty"`  // platform message ID
+	MediaScope string            `json:"media_scope,omitempty"` // media lifecycle scope
 	SessionKey string            `json:"session_key"`
 	Metadata   map[string]string `json:"metadata,omitempty"`
 }
@@ -16,4 +35,18 @@ type OutboundMessage struct {
 	Content string `json:"content"`
 }

-type MessageHandler func(InboundMessage) error
+// MediaPart describes a single media attachment to send.
+type MediaPart struct {
+	Type        string `json:"type"`                   // "image" | "audio" | "video" | "file"
+	Ref         string `json:"ref"`                    // media store ref, e.g. "media://abc123"
+	Caption     string `json:"caption,omitempty"`      // optional caption text
+	Filename    string `json:"filename,omitempty"`     // original filename hint
+	ContentType string `json:"content_type,omitempty"` // MIME type hint
+}
+
+// OutboundMediaMessage carries media attachments from Agent to channels via the bus.
+type OutboundMediaMessage struct {
+	Channel string      `json:"channel"`
+	ChatID  string      `json:"chat_id"`
+	Parts   []MediaPart `json:"parts"`
+}
@@ -2,11 +2,44 @@ package channels

 import (
 	"context"
+	"crypto/rand"
+	"encoding/binary"
+	"encoding/hex"
+	"strconv"
 	"strings"
+	"sync/atomic"
+	"time"

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

+var (
+	uniqueIDCounter uint64
+	uniqueIDPrefix  string
+)
+
+func init() {
+	// One-time read from crypto/rand for a unique prefix (single syscall).
+	var b [8]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		// fallback to time-based prefix
+		binary.BigEndian.PutUint64(b[:], uint64(time.Now().UnixNano()))
+	}
+	uniqueIDPrefix = hex.EncodeToString(b[:])
+}
+
+// uniqueID generates a process-unique ID using a random prefix and an atomic counter.
+// This ID is intended for internal correlation (e.g. media scope keys) and is NOT
+// cryptographically secure — it must not be used in contexts where unpredictability matters.
+func uniqueID() string {
+	n := atomic.AddUint64(&uniqueIDCounter, 1)
+	return uniqueIDPrefix + strconv.FormatUint(n, 16)
+}
+
 type Channel interface {
 	Name() string
 	Start(ctx context.Context) error
@@ -14,32 +47,126 @@ type Channel interface {
 	Send(ctx context.Context, msg bus.OutboundMessage) error
 	IsRunning() bool
 	IsAllowed(senderID string) bool
+	IsAllowedSender(sender bus.SenderInfo) bool
+	ReasoningChannelID() string
+}
+
+// BaseChannelOption is a functional option for configuring a BaseChannel.
+type BaseChannelOption func(*BaseChannel)
+
+// WithMaxMessageLength sets the maximum message length (in runes) for a channel.
+// Messages exceeding this limit will be automatically split by the Manager.
+// A value of 0 means no limit.
+func WithMaxMessageLength(n int) BaseChannelOption {
+	return func(c *BaseChannel) { c.maxMessageLength = n }
+}
+
+// WithGroupTrigger sets the group trigger configuration for a channel.
+func WithGroupTrigger(gt config.GroupTriggerConfig) BaseChannelOption {
+	return func(c *BaseChannel) { c.groupTrigger = gt }
+}
+
+// WithReasoningChannelID sets the reasoning channel ID where thoughts should be sent.
+func WithReasoningChannelID(id string) BaseChannelOption {
+	return func(c *BaseChannel) { c.reasoningChannelID = id }
+}
+
+// MessageLengthProvider is an opt-in interface that channels implement
+// to advertise their maximum message length. The Manager uses this via
+// type assertion to decide whether to split outbound messages.
+type MessageLengthProvider interface {
+	MaxMessageLength() int
 }

 type BaseChannel struct {
-	config    any
-	bus       *bus.MessageBus
-	running   bool
-	name      string
-	allowList []string
+	config              any
+	bus                 *bus.MessageBus
+	running             atomic.Bool
+	name                string
+	allowList           []string
+	maxMessageLength    int
+	groupTrigger        config.GroupTriggerConfig
+	mediaStore          media.MediaStore
+	placeholderRecorder PlaceholderRecorder
+	owner               Channel // the concrete channel that embeds this BaseChannel
+	reasoningChannelID  string
 }

-func NewBaseChannel(name string, config any, bus *bus.MessageBus, allowList []string) *BaseChannel {
-	return &BaseChannel{
+func NewBaseChannel(
+	name string,
+	config any,
+	bus *bus.MessageBus,
+	allowList []string,
+	opts ...BaseChannelOption,
+) *BaseChannel {
+	bc := &BaseChannel{
 		config:    config,
 		bus:       bus,
 		name:      name,
 		allowList: allowList,
-		running:   false,
 	}
+	for _, opt := range opts {
+		opt(bc)
+	}
+	return bc
+}
+
+// MaxMessageLength returns the maximum message length (in runes) for this channel.
+// A value of 0 means no limit.
+func (c *BaseChannel) MaxMessageLength() int {
+	return c.maxMessageLength
+}
+
+// ShouldRespondInGroup determines whether the bot should respond in a group chat.
+// Each channel is responsible for:
+//  1. Detecting isMentioned (platform-specific)
+//  2. Stripping bot mention from content (platform-specific)
+//  3. Calling this method to get the group response decision
+//
+// Logic:
+//   - If isMentioned → always respond
+//   - If mention_only configured and not mentioned → ignore
+//   - If prefixes configured → respond if content starts with any prefix (strip it)
+//   - If prefixes configured but no match and not mentioned → ignore
+//   - Otherwise (no group_trigger configured) → respond to all (permissive default)
+func (c *BaseChannel) ShouldRespondInGroup(isMentioned bool, content string) (bool, string) {
+	gt := c.groupTrigger
+
+	// Mentioned → always respond
+	if isMentioned {
+		return true, strings.TrimSpace(content)
+	}
+
+	// mention_only → require mention
+	if gt.MentionOnly {
+		return false, content
+	}
+
+	// Prefix matching
+	if len(gt.Prefixes) > 0 {
+		for _, prefix := range gt.Prefixes {
+			if prefix != "" && strings.HasPrefix(content, prefix) {
+				return true, strings.TrimSpace(strings.TrimPrefix(content, prefix))
+			}
+		}
+		// Prefixes configured but none matched and not mentioned → ignore
+		return false, content
+	}
+
+	// No group_trigger configured → permissive (respond to all)
+	return true, strings.TrimSpace(content)
 }

 func (c *BaseChannel) Name() string {
 	return c.name
 }

+func (c *BaseChannel) ReasoningChannelID() string {
+	return c.reasoningChannelID
+}
+
 func (c *BaseChannel) IsRunning() bool {
-	return c.running
+	return c.running.Load()
 }

 func (c *BaseChannel) IsAllowed(senderID string) bool {
@@ -81,23 +208,130 @@ func (c *BaseChannel) IsAllowed(senderID string) bool {
 	return false
 }

-func (c *BaseChannel) HandleMessage(senderID, chatID, content string, media []string, metadata map[string]string) {
-	if !c.IsAllowed(senderID) {
-		return
+// IsAllowedSender checks whether a structured SenderInfo is permitted by the allow-list.
+// It delegates to identity.MatchAllowed for each entry, providing unified matching
+// across all legacy formats and the new canonical "platform:id" format.
+func (c *BaseChannel) IsAllowedSender(sender bus.SenderInfo) bool {
+	if len(c.allowList) == 0 {
+		return true
 	}

+	for _, allowed := range c.allowList {
+		if identity.MatchAllowed(sender, allowed) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (c *BaseChannel) HandleMessage(
+	ctx context.Context,
+	peer bus.Peer,
+	messageID, senderID, chatID, content string,
+	media []string,
+	metadata map[string]string,
+	senderOpts ...bus.SenderInfo,
+) {
+	// Use SenderInfo-based allow check when available, else fall back to string
+	var sender bus.SenderInfo
+	if len(senderOpts) > 0 {
+		sender = senderOpts[0]
+	}
+	if sender.CanonicalID != "" || sender.PlatformID != "" {
+		if !c.IsAllowedSender(sender) {
+			return
+		}
+	} else {
+		if !c.IsAllowed(senderID) {
+			return
+		}
+	}
+
+	// Set SenderID to canonical if available, otherwise keep the raw senderID
+	resolvedSenderID := senderID
+	if sender.CanonicalID != "" {
+		resolvedSenderID = sender.CanonicalID
+	}
+
+	scope := BuildMediaScope(c.name, chatID, messageID)
+
 	msg := bus.InboundMessage{
-		Channel:  c.name,
-		SenderID: senderID,
-		ChatID:   chatID,
-		Content:  content,
-		Media:    media,
-		Metadata: metadata,
+		Channel:    c.name,
+		SenderID:   resolvedSenderID,
+		Sender:     sender,
+		ChatID:     chatID,
+		Content:    content,
+		Media:      media,
+		Peer:       peer,
+		MessageID:  messageID,
+		MediaScope: scope,
+		Metadata:   metadata,
 	}

-	c.bus.PublishInbound(msg)
+	// Auto-trigger typing indicator, message reaction, and placeholder before publishing.
+	// Each capability is independent — all three may fire for the same message.
+	if c.owner != nil && c.placeholderRecorder != nil {
+		// Typing — independent pipeline
+		if tc, ok := c.owner.(TypingCapable); ok {
+			if stop, err := tc.StartTyping(ctx, chatID); err == nil {
+				c.placeholderRecorder.RecordTypingStop(c.name, chatID, stop)
+			}
+		}
+		// Reaction — independent pipeline
+		if rc, ok := c.owner.(ReactionCapable); ok && messageID != "" {
+			if undo, err := rc.ReactToMessage(ctx, chatID, messageID); err == nil {
+				c.placeholderRecorder.RecordReactionUndo(c.name, chatID, undo)
+			}
+		}
+		// Placeholder — independent pipeline
+		if pc, ok := c.owner.(PlaceholderCapable); ok {
+			if phID, err := pc.SendPlaceholder(ctx, chatID); err == nil && phID != "" {
+				c.placeholderRecorder.RecordPlaceholder(c.name, chatID, phID)
+			}
+		}
+	}
+
+	if err := c.bus.PublishInbound(ctx, msg); err != nil {
+		logger.ErrorCF("channels", "Failed to publish inbound message", map[string]any{
+			"channel": c.name,
+			"chat_id": chatID,
+			"error":   err.Error(),
+		})
+	}
 }

-func (c *BaseChannel) setRunning(running bool) {
-	c.running = running
+func (c *BaseChannel) SetRunning(running bool) {
+	c.running.Store(running)
+}
+
+// SetMediaStore injects a MediaStore into the channel.
+func (c *BaseChannel) SetMediaStore(s media.MediaStore) { c.mediaStore = s }
+
+// GetMediaStore returns the injected MediaStore (may be nil).
+func (c *BaseChannel) GetMediaStore() media.MediaStore { return c.mediaStore }
+
+// SetPlaceholderRecorder injects a PlaceholderRecorder into the channel.
+func (c *BaseChannel) SetPlaceholderRecorder(r PlaceholderRecorder) {
+	c.placeholderRecorder = r
+}
+
+// GetPlaceholderRecorder returns the injected PlaceholderRecorder (may be nil).
+func (c *BaseChannel) GetPlaceholderRecorder() PlaceholderRecorder {
+	return c.placeholderRecorder
+}
+
+// SetOwner injects the concrete channel that embeds this BaseChannel.
+// This allows HandleMessage to auto-trigger TypingCapable / ReactionCapable / PlaceholderCapable.
+func (c *BaseChannel) SetOwner(ch Channel) {
+	c.owner = ch
+}
+
+// BuildMediaScope constructs a scope key for media lifecycle tracking.
+func BuildMediaScope(channel, chatID, messageID string) string {
+	id := messageID
+	if id == "" {
+		id = uniqueID()
+	}
+	return channel + ":" + chatID + ":" + id
 }
@@ -1,6 +1,11 @@
 package channels

-import "testing"
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)

 func TestBaseChannelIsAllowed(t *testing.T) {
 	tests := []struct {
@@ -50,3 +55,211 @@ func TestBaseChannelIsAllowed(t *testing.T) {
 		})
 	}
 }
+
+func TestShouldRespondInGroup(t *testing.T) {
+	tests := []struct {
+		name        string
+		gt          config.GroupTriggerConfig
+		isMentioned bool
+		content     string
+		wantRespond bool
+		wantContent string
+	}{
+		{
+			name:        "no config - permissive default",
+			gt:          config.GroupTriggerConfig{},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "no config - mentioned",
+			gt:          config.GroupTriggerConfig{},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "mention_only - not mentioned",
+			gt:          config.GroupTriggerConfig{MentionOnly: true},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: false,
+			wantContent: "hello world",
+		},
+		{
+			name:        "mention_only - mentioned",
+			gt:          config.GroupTriggerConfig{MentionOnly: true},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "prefix match",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "/ask hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+		{
+			name:        "prefix no match - not mentioned",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "hello world",
+			wantRespond: false,
+			wantContent: "hello world",
+		},
+		{
+			name:        "prefix no match - but mentioned",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask"}},
+			isMentioned: true,
+			content:     "hello world",
+			wantRespond: true,
+			wantContent: "hello world",
+		},
+		{
+			name:        "multiple prefixes - second matches",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask", "/bot"}},
+			isMentioned: false,
+			content:     "/bot help me",
+			wantRespond: true,
+			wantContent: "help me",
+		},
+		{
+			name:        "mention_only with prefixes - mentioned overrides",
+			gt:          config.GroupTriggerConfig{MentionOnly: true, Prefixes: []string{"/ask"}},
+			isMentioned: true,
+			content:     "hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+		{
+			name:        "mention_only with prefixes - not mentioned, no prefix",
+			gt:          config.GroupTriggerConfig{MentionOnly: true, Prefixes: []string{"/ask"}},
+			isMentioned: false,
+			content:     "hello",
+			wantRespond: false,
+			wantContent: "hello",
+		},
+		{
+			name:        "empty prefix in list is skipped",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"", "/ask"}},
+			isMentioned: false,
+			content:     "/ask test",
+			wantRespond: true,
+			wantContent: "test",
+		},
+		{
+			name:        "prefix strips leading whitespace after prefix",
+			gt:          config.GroupTriggerConfig{Prefixes: []string{"/ask "}},
+			isMentioned: false,
+			content:     "/ask hello",
+			wantRespond: true,
+			wantContent: "hello",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ch := NewBaseChannel("test", nil, nil, nil, WithGroupTrigger(tt.gt))
+			gotRespond, gotContent := ch.ShouldRespondInGroup(tt.isMentioned, tt.content)
+			if gotRespond != tt.wantRespond {
+				t.Errorf("ShouldRespondInGroup() respond = %v, want %v", gotRespond, tt.wantRespond)
+			}
+			if gotContent != tt.wantContent {
+				t.Errorf("ShouldRespondInGroup() content = %q, want %q", gotContent, tt.wantContent)
+			}
+		})
+	}
+}
+
+func TestIsAllowedSender(t *testing.T) {
+	tests := []struct {
+		name      string
+		allowList []string
+		sender    bus.SenderInfo
+		want      bool
+	}{
+		{
+			name:      "empty allowlist allows all",
+			allowList: nil,
+			sender:    bus.SenderInfo{PlatformID: "anyone"},
+			want:      true,
+		},
+		{
+			name:      "numeric ID matches PlatformID",
+			allowList: []string{"123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: true,
+		},
+		{
+			name:      "canonical format matches",
+			allowList: []string{"telegram:123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: true,
+		},
+		{
+			name:      "canonical format wrong platform",
+			allowList: []string{"discord:123456"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: false,
+		},
+		{
+			name:      "@username matches",
+			allowList: []string{"@alice"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+				Username:    "alice",
+			},
+			want: true,
+		},
+		{
+			name:      "compound id|username matches by ID",
+			allowList: []string{"123456|alice"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+				Username:    "alice",
+			},
+			want: true,
+		},
+		{
+			name:      "non matching sender denied",
+			allowList: []string{"654321"},
+			sender: bus.SenderInfo{
+				Platform:    "telegram",
+				PlatformID:  "123456",
+				CanonicalID: "telegram:123456",
+			},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ch := NewBaseChannel("test", nil, nil, tt.allowList)
+			if got := ch.IsAllowedSender(tt.sender); got != tt.want {
+				t.Fatalf("IsAllowedSender(%+v) = %v, want %v", tt.sender, got, tt.want)
+			}
+		})
+	}
+}
@@ -1,7 +1,7 @@
 // PicoClaw - Ultra-lightweight personal AI agent
 // DingTalk channel implementation using Stream Mode

-package channels
+package dingtalk

 import (
 	"context"
@@ -12,7 +12,9 @@ import (
 	"github.com/open-dingtalk/dingtalk-stream-sdk-go/client"

 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
@@ -20,7 +22,7 @@ import (
 // DingTalkChannel implements the Channel interface for DingTalk (钉钉)
 // It uses WebSocket for receiving messages via stream mode and API for sending
 type DingTalkChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config       config.DingTalkConfig
 	clientID     string
 	clientSecret string
@@ -37,7 +39,11 @@ func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (
 		return nil, fmt.Errorf("dingtalk client_id and client_secret are required")
 	}

-	base := NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(20000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &DingTalkChannel{
 		BaseChannel:  base,
@@ -70,7 +76,7 @@ func (c *DingTalkChannel) Start(ctx context.Context) error {
 		return fmt.Errorf("failed to start stream client: %w", err)
 	}

-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("dingtalk", "DingTalk channel started (Stream Mode)")
 	return nil
 }
@@ -87,7 +93,7 @@ func (c *DingTalkChannel) Stop(ctx context.Context) error {
 		c.streamClient.Close()
 	}

-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("dingtalk", "DingTalk channel stopped")
 	return nil
 }
@@ -95,7 +101,7 @@ func (c *DingTalkChannel) Stop(ctx context.Context) error {
 // Send sends a message to DingTalk via the chatbot reply API
 func (c *DingTalkChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("dingtalk channel not running")
+		return channels.ErrNotRunning
 	}

 	// Get session webhook from storage
@@ -159,12 +165,17 @@ func (c *DingTalkChannel) onChatBotMessageReceived(
 		"session_webhook":   data.SessionWebhook,
 	}

+	var peer bus.Peer
 	if data.ConversationType == "1" {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	} else {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = data.ConversationId
+		peer = bus.Peer{Kind: "group", ID: data.ConversationId}
+		// In group chats, apply unified group trigger filtering
+		respond, cleaned := c.ShouldRespondInGroup(false, content)
+		if !respond {
+			return nil, nil
+		}
+		content = cleaned
 	}

 	logger.DebugCF("dingtalk", "Received message", map[string]any{
@@ -173,8 +184,20 @@ func (c *DingTalkChannel) onChatBotMessageReceived(
 		"preview":     utils.Truncate(content, 50),
 	})

+	// Build sender info
+	sender := bus.SenderInfo{
+		Platform:    "dingtalk",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("dingtalk", senderID),
+		DisplayName: senderNick,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return nil, nil
+	}
+
 	// Handle the message through the base channel
-	c.HandleMessage(senderID, chatID, content, nil, metadata)
+	c.HandleMessage(ctx, peer, "", senderID, chatID, content, nil, metadata, sender)

 	// Return nil to indicate we've handled the message asynchronously
 	// The response will be sent through the message bus
@@ -197,7 +220,7 @@ func (c *DingTalkChannel) SendDirectReply(ctx context.Context, sessionWebhook, c
 		contentBytes,
 	)
 	if err != nil {
-		return fmt.Errorf("failed to send reply: %w", err)
+		return fmt.Errorf("dingtalk send: %w", channels.ErrTemporary)
 	}

 	return nil
@@ -0,0 +1,13 @@
+package dingtalk
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("dingtalk", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewDingTalkChannel(cfg.Channels.DingTalk, b)
+	})
+}
@@ -1,4 +1,4 @@
-package channels
+package discord

 import (
 	"context"
@@ -14,26 +14,27 @@ import (
 	"github.com/gorilla/websocket"

 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"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"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )

 const (
-	transcriptionTimeout = 30 * time.Second
-	sendTimeout          = 10 * time.Second
+	sendTimeout = 10 * time.Second
 )

 type DiscordChannel struct {
-	*BaseChannel
-	session     *discordgo.Session
-	config      config.DiscordConfig
-	transcriber *voice.GroqTranscriber
-	ctx         context.Context
-	typingMu    sync.Mutex
-	typingStop  map[string]chan struct{} // chatID → stop signal
-	botUserID   string                   // stored for mention checking
+	*channels.BaseChannel
+	session    *discordgo.Session
+	config     config.DiscordConfig
+	ctx        context.Context
+	cancel     context.CancelFunc
+	typingMu   sync.Mutex
+	typingStop map[string]chan struct{} // chatID → stop signal
+	botUserID  string                   // stored for mention checking
 }

 func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
@@ -45,34 +46,25 @@ func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordC
 	if err := applyDiscordProxy(session, cfg.Proxy); err != nil {
 		return nil, err
 	}
-
-	base := NewBaseChannel("discord", cfg, bus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("discord", cfg, bus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(2000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &DiscordChannel{
 		BaseChannel: base,
 		session:     session,
 		config:      cfg,
-		transcriber: nil,
 		ctx:         context.Background(),
 		typingStop:  make(map[string]chan struct{}),
 	}, nil
 }

-func (c *DiscordChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
-func (c *DiscordChannel) getContext() context.Context {
-	if c.ctx == nil {
-		return context.Background()
-	}
-	return c.ctx
-}
-
 func (c *DiscordChannel) Start(ctx context.Context) error {
 	logger.InfoC("discord", "Starting Discord bot")

-	c.ctx = ctx
+	c.ctx, c.cancel = context.WithCancel(ctx)

 	// Get bot user ID before opening session to avoid race condition
 	botUser, err := c.session.User("@me")
@@ -87,7 +79,7 @@ func (c *DiscordChannel) Start(ctx context.Context) error {
 		return fmt.Errorf("failed to open discord session: %w", err)
 	}

-	c.setRunning(true)
+	c.SetRunning(true)

 	logger.InfoCF("discord", "Discord bot connected", map[string]any{
 		"username": botUser.Username,
@@ -99,7 +91,7 @@ func (c *DiscordChannel) Start(ctx context.Context) error {

 func (c *DiscordChannel) Stop(ctx context.Context) error {
 	logger.InfoC("discord", "Stopping Discord bot")
-	c.setRunning(false)
+	c.SetRunning(false)

 	// Stop all typing goroutines before closing session
 	c.typingMu.Lock()
@@ -109,6 +101,11 @@ func (c *DiscordChannel) Stop(ctx context.Context) error {
 	}
 	c.typingMu.Unlock()

+	// Cancel our context so typing goroutines using c.ctx.Done() exit
+	if c.cancel != nil {
+		c.cancel()
+	}
+
 	if err := c.session.Close(); err != nil {
 		return fmt.Errorf("failed to close discord session: %w", err)
 	}
@@ -117,10 +114,8 @@ func (c *DiscordChannel) Stop(ctx context.Context) error {
 }

 func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	c.stopTyping(msg.ChatID)
-
 	if !c.IsRunning() {
-		return fmt.Errorf("discord bot not running")
+		return channels.ErrNotRunning
 	}

 	channelID := msg.ChatID
@@ -128,20 +123,133 @@ func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) erro
 		return fmt.Errorf("channel ID is empty")
 	}

-	runes := []rune(msg.Content)
-	if len(runes) == 0 {
+	if len([]rune(msg.Content)) == 0 {
 		return nil
 	}

-	chunks := utils.SplitMessage(msg.Content, 2000) // Split messages into chunks, Discord length limit: 2000 chars
+	return c.sendChunk(ctx, channelID, msg.Content)
+}

-	for _, chunk := range chunks {
-		if err := c.sendChunk(ctx, channelID, chunk); err != nil {
-			return err
+// SendMedia implements the channels.MediaSender interface.
+func (c *DiscordChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	channelID := msg.ChatID
+	if channelID == "" {
+		return fmt.Errorf("channel ID is empty")
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// Collect all files into a single ChannelMessageSendComplex call
+	files := make([]*discordgo.File, 0, len(msg.Parts))
+	var caption string
+
+	for _, part := range msg.Parts {
+		localPath, err := store.Resolve(part.Ref)
+		if err != nil {
+			logger.ErrorCF("discord", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		file, err := os.Open(localPath)
+		if err != nil {
+			logger.ErrorCF("discord", "Failed to open media file", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			continue
+		}
+		// Note: discordgo reads from the Reader and we can't close it before send
+
+		filename := part.Filename
+		if filename == "" {
+			filename = "file"
+		}
+
+		files = append(files, &discordgo.File{
+			Name:        filename,
+			ContentType: part.ContentType,
+			Reader:      file,
+		})
+
+		if part.Caption != "" && caption == "" {
+			caption = part.Caption
 		}
 	}

-	return nil
+	if len(files) == 0 {
+		return nil
+	}
+
+	sendCtx, cancel := context.WithTimeout(ctx, sendTimeout)
+	defer cancel()
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := c.session.ChannelMessageSendComplex(channelID, &discordgo.MessageSend{
+			Content: caption,
+			Files:   files,
+		})
+		done <- err
+	}()
+
+	select {
+	case err := <-done:
+		// Close all file readers
+		for _, f := range files {
+			if closer, ok := f.Reader.(*os.File); ok {
+				closer.Close()
+			}
+		}
+		if err != nil {
+			return fmt.Errorf("discord send media: %w", channels.ErrTemporary)
+		}
+		return nil
+	case <-sendCtx.Done():
+		// Close all file readers
+		for _, f := range files {
+			if closer, ok := f.Reader.(*os.File); ok {
+				closer.Close()
+			}
+		}
+		return sendCtx.Err()
+	}
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *DiscordChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	_, err := c.session.ChannelMessageEdit(chatID, messageID, content)
+	return err
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+// It sends a placeholder message that will later be edited to the actual
+// response via EditMessage (channels.MessageEditor).
+func (c *DiscordChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		return "", nil
+	}
+
+	text := c.config.Placeholder.Text
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	msg, err := c.session.ChannelMessageSend(chatID, text)
+	if err != nil {
+		return "", err
+	}
+
+	return msg.ID, nil
 }

 func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content string) error {
@@ -158,11 +266,11 @@ func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content strin
 	select {
 	case err := <-done:
 		if err != nil {
-			return fmt.Errorf("failed to send discord message: %w", err)
+			return fmt.Errorf("discord send: %w", channels.ErrTemporary)
 		}
 		return nil
 	case <-sendCtx.Done():
-		return fmt.Errorf("send message timeout: %w", sendCtx.Err())
+		return sendCtx.Err()
 	}
 }

@@ -183,17 +291,32 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		return
 	}

-	// Check allowlist first to avoid downloading attachments and transcribing for rejected users
-	if !c.IsAllowed(m.Author.ID) {
+	// Check allowlist first to avoid downloading attachments for rejected users
+	sender := bus.SenderInfo{
+		Platform:    "discord",
+		PlatformID:  m.Author.ID,
+		CanonicalID: identity.BuildCanonicalID("discord", m.Author.ID),
+		Username:    m.Author.Username,
+	}
+	// Build display name
+	displayName := m.Author.Username
+	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
+		displayName += "#" + m.Author.Discriminator
+	}
+	sender.DisplayName = displayName
+
+	if !c.IsAllowedSender(sender) {
 		logger.DebugCF("discord", "Message rejected by allowlist", map[string]any{
 			"user_id": m.Author.ID,
 		})
 		return
 	}

-	// If configured to only respond to mentions, check if bot is mentioned
-	// Skip this check for DMs (GuildID is empty) - DMs should always be responded to
-	if c.config.MentionOnly && m.GuildID != "" {
+	content := m.Content
+
+	// In guild (group) channels, apply unified group trigger filtering
+	// DMs (GuildID is empty) always get a response
+	if m.GuildID != "" {
 		isMentioned := false
 		for _, mention := range m.Mentions {
 			if mention.ID == c.botUserID {
@@ -201,36 +324,39 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 				break
 			}
 		}
-		if !isMentioned {
-			logger.DebugCF("discord", "Message ignored - bot not mentioned", map[string]any{
+		content = c.stripBotMention(content)
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			logger.DebugCF("discord", "Group message ignored by group trigger", map[string]any{
 				"user_id": m.Author.ID,
 			})
 			return
 		}
+		content = cleaned
+	} else {
+		// DMs: just strip bot mention without filtering
+		content = c.stripBotMention(content)
 	}

 	senderID := m.Author.ID
-	senderName := m.Author.Username
-	if m.Author.Discriminator != "" && m.Author.Discriminator != "0" {
-		senderName += "#" + m.Author.Discriminator
-	}

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

-	// Ensure temp files are cleaned up when function returns
-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("discord", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("discord", m.ChannelID, m.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "discord",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}

 	for _, attachment := range m.Attachments {
 		isAudio := utils.IsAudioFile(attachment.Filename, attachment.ContentType)
@@ -238,30 +364,8 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		if isAudio {
 			localPath := c.downloadAttachment(attachment.URL, attachment.Filename)
 			if localPath != "" {
-				localFiles = append(localFiles, localPath)
-
-				var transcribedText string
-				if c.transcriber != nil && c.transcriber.IsAvailable() {
-					ctx, cancel := context.WithTimeout(c.getContext(), transcriptionTimeout)
-					result, err := c.transcriber.Transcribe(ctx, localPath)
-					cancel() // Release context resources immediately to avoid leaks in for loop
-
-					if err != nil {
-						logger.ErrorCF("discord", "Voice transcription failed", map[string]any{
-							"error": err.Error(),
-						})
-						transcribedText = fmt.Sprintf("[audio: %s (transcription failed)]", attachment.Filename)
-					} else {
-						transcribedText = fmt.Sprintf("[audio transcription: %s]", result.Text)
-						logger.DebugCF("discord", "Audio transcribed successfully", map[string]any{
-							"text": result.Text,
-						})
-					}
-				} else {
-					transcribedText = fmt.Sprintf("[audio: %s]", attachment.Filename)
-				}
-
-				content = appendContent(content, transcribedText)
+				mediaPaths = append(mediaPaths, storeMedia(localPath, attachment.Filename))
+				content = appendContent(content, fmt.Sprintf("[audio: %s]", attachment.Filename))
 			} else {
 				logger.WarnCF("discord", "Failed to download audio attachment", map[string]any{
 					"url":      attachment.URL,
@@ -284,11 +388,8 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		content = "[media only]"
 	}

-	// Start typing after all early returns — guaranteed to have a matching Send()
-	c.startTyping(m.ChannelID)
-
 	logger.DebugCF("discord", "Received message", map[string]any{
-		"sender_name": senderName,
+		"sender_name": sender.DisplayName,
 		"sender_id":   senderID,
 		"preview":     utils.Truncate(content, 50),
 	})
@@ -300,19 +401,18 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		peerID = senderID
 	}

+	peer := bus.Peer{Kind: peerKind, ID: peerID}
+
 	metadata := map[string]string{
-		"message_id":   m.ID,
 		"user_id":      senderID,
 		"username":     m.Author.Username,
-		"display_name": senderName,
+		"display_name": sender.DisplayName,
 		"guild_id":     m.GuildID,
 		"channel_id":   m.ChannelID,
 		"is_dm":        fmt.Sprintf("%t", m.GuildID == ""),
-		"peer_kind":    peerKind,
-		"peer_id":      peerID,
 	}

-	c.HandleMessage(senderID, m.ChannelID, content, mediaPaths, metadata)
+	c.HandleMessage(c.ctx, peer, m.ID, senderID, m.ChannelID, content, mediaPaths, metadata, sender)
 }

 // startTyping starts a continuous typing indicator loop for the given chatID.
@@ -361,6 +461,13 @@ func (c *DiscordChannel) stopTyping(chatID string) {
 	}
 }

+// StartTyping implements channels.TypingCapable.
+// It starts a continuous typing indicator and returns an idempotent stop function.
+func (c *DiscordChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	c.startTyping(chatID)
+	return func() { c.stopTyping(chatID) }, nil
+}
+
 func (c *DiscordChannel) downloadAttachment(url, filename string) string {
 	return utils.DownloadFile(url, filename, utils.DownloadOptions{
 		LoggerPrefix: "discord",
@@ -386,7 +493,7 @@ func applyDiscordProxy(session *discordgo.Session, proxyAddr string) error {

 	transport := &http.Transport{Proxy: proxyFunc}
 	session.Client = &http.Client{
-		Timeout:   20 * time.Second,
+		Timeout:   sendTimeout,
 		Transport: transport,
 	}

@@ -1,7 +1,4 @@
-//go:build discord_proxy
-// +build discord_proxy
-
-package channels
+package discord

 import (
 	"net/http"
@@ -17,7 +14,7 @@ func TestApplyDiscordProxy_CustomProxy(t *testing.T) {
 		t.Fatalf("discordgo.New() error: %v", err)
 	}

-	if err := applyDiscordProxy(session, "http://127.0.0.1:7890"); err != nil {
+	if err = applyDiscordProxy(session, "http://127.0.0.1:7890"); err != nil {
 		t.Fatalf("applyDiscordProxy() error: %v", err)
 	}

@@ -59,7 +56,7 @@ func TestApplyDiscordProxy_FromEnvironment(t *testing.T) {
 		t.Fatalf("discordgo.New() error: %v", err)
 	}

-	if err := applyDiscordProxy(session, ""); err != nil {
+	if err = applyDiscordProxy(session, ""); err != nil {
 		t.Fatalf("applyDiscordProxy() error: %v", err)
 	}

@@ -88,7 +85,7 @@ func TestApplyDiscordProxy_InvalidProxyURL(t *testing.T) {
 		t.Fatalf("discordgo.New() error: %v", err)
 	}

-	if err := applyDiscordProxy(session, "://bad-proxy"); err == nil {
+	if err = applyDiscordProxy(session, "://bad-proxy"); err == nil {
 		t.Fatal("applyDiscordProxy() expected error for invalid proxy URL, got nil")
 	}
 }
@@ -0,0 +1,13 @@
+package discord
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("discord", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewDiscordChannel(cfg.Channels.Discord, b)
+	})
+}
@@ -0,0 +1,21 @@
+package channels
+
+import "errors"
+
+var (
+	// ErrNotRunning indicates the channel is not running.
+	// Manager will not retry.
+	ErrNotRunning = errors.New("channel not running")
+
+	// ErrRateLimit indicates the platform returned a rate-limit response (e.g. HTTP 429).
+	// Manager will wait a fixed delay and retry.
+	ErrRateLimit = errors.New("rate limited")
+
+	// ErrTemporary indicates a transient failure (e.g. network timeout, 5xx).
+	// Manager will use exponential backoff and retry.
+	ErrTemporary = errors.New("temporary failure")
+
+	// ErrSendFailed indicates a permanent failure (e.g. invalid chat ID, 4xx non-429).
+	// Manager will not retry.
+	ErrSendFailed = errors.New("send failed")
+)
@@ -0,0 +1,56 @@
+package channels
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestErrorsIs(t *testing.T) {
+	wrapped := fmt.Errorf("telegram API: %w", ErrRateLimit)
+	if !errors.Is(wrapped, ErrRateLimit) {
+		t.Error("wrapped ErrRateLimit should match")
+	}
+	if errors.Is(wrapped, ErrTemporary) {
+		t.Error("wrapped ErrRateLimit should not match ErrTemporary")
+	}
+}
+
+func TestErrorsIsAllTypes(t *testing.T) {
+	sentinels := []error{ErrNotRunning, ErrRateLimit, ErrTemporary, ErrSendFailed}
+
+	for _, sentinel := range sentinels {
+		wrapped := fmt.Errorf("context: %w", sentinel)
+		if !errors.Is(wrapped, sentinel) {
+			t.Errorf("wrapped %v should match itself", sentinel)
+		}
+
+		// Verify it doesn't match other sentinel errors
+		for _, other := range sentinels {
+			if other == sentinel {
+				continue
+			}
+			if errors.Is(wrapped, other) {
+				t.Errorf("wrapped %v should not match %v", sentinel, other)
+			}
+		}
+	}
+}
+
+func TestErrorMessages(t *testing.T) {
+	tests := []struct {
+		err  error
+		want string
+	}{
+		{ErrNotRunning, "channel not running"},
+		{ErrRateLimit, "rate limited"},
+		{ErrTemporary, "temporary failure"},
+		{ErrSendFailed, "send failed"},
+	}
+
+	for _, tt := range tests {
+		if got := tt.err.Error(); got != tt.want {
+			t.Errorf("error message = %q, want %q", got, tt.want)
+		}
+	}
+}
@@ -0,0 +1,30 @@
+package channels
+
+import (
+	"fmt"
+	"net/http"
+)
+
+// ClassifySendError wraps a raw error with the appropriate sentinel based on
+// an HTTP status code. Channels that perform HTTP API calls should use this
+// in their Send path.
+func ClassifySendError(statusCode int, rawErr error) error {
+	switch {
+	case statusCode == http.StatusTooManyRequests:
+		return fmt.Errorf("%w: %v", ErrRateLimit, rawErr)
+	case statusCode >= 500:
+		return fmt.Errorf("%w: %v", ErrTemporary, rawErr)
+	case statusCode >= 400:
+		return fmt.Errorf("%w: %v", ErrSendFailed, rawErr)
+	default:
+		return rawErr
+	}
+}
+
+// ClassifyNetError wraps a network/timeout error as ErrTemporary.
+func ClassifyNetError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("%w: %v", ErrTemporary, err)
+}
@@ -0,0 +1,97 @@
+package channels
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+)
+
+func TestClassifySendError(t *testing.T) {
+	raw := fmt.Errorf("some API error")
+
+	tests := []struct {
+		name       string
+		statusCode int
+		wantIs     error
+		wantNil    bool
+	}{
+		{"429 -> ErrRateLimit", 429, ErrRateLimit, false},
+		{"500 -> ErrTemporary", 500, ErrTemporary, false},
+		{"502 -> ErrTemporary", 502, ErrTemporary, false},
+		{"503 -> ErrTemporary", 503, ErrTemporary, false},
+		{"400 -> ErrSendFailed", 400, ErrSendFailed, false},
+		{"403 -> ErrSendFailed", 403, ErrSendFailed, false},
+		{"404 -> ErrSendFailed", 404, ErrSendFailed, false},
+		{"200 -> raw error", 200, nil, false},
+		{"201 -> raw error", 201, nil, false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := ClassifySendError(tt.statusCode, raw)
+			if err == nil {
+				t.Fatal("expected non-nil error")
+			}
+			if tt.wantIs != nil {
+				if !errors.Is(err, tt.wantIs) {
+					t.Errorf("errors.Is(err, %v) = false, want true; err = %v", tt.wantIs, err)
+				}
+			} else {
+				// Should return the raw error unchanged
+				if err != raw {
+					t.Errorf("expected raw error to be returned unchanged for status %d, got %v", tt.statusCode, err)
+				}
+			}
+		})
+	}
+}
+
+func TestClassifySendErrorNoFalsePositive(t *testing.T) {
+	raw := fmt.Errorf("some error")
+
+	// 429 should NOT match ErrTemporary or ErrSendFailed
+	err := ClassifySendError(429, raw)
+	if errors.Is(err, ErrTemporary) {
+		t.Error("429 should not match ErrTemporary")
+	}
+	if errors.Is(err, ErrSendFailed) {
+		t.Error("429 should not match ErrSendFailed")
+	}
+
+	// 500 should NOT match ErrRateLimit or ErrSendFailed
+	err = ClassifySendError(500, raw)
+	if errors.Is(err, ErrRateLimit) {
+		t.Error("500 should not match ErrRateLimit")
+	}
+	if errors.Is(err, ErrSendFailed) {
+		t.Error("500 should not match ErrSendFailed")
+	}
+
+	// 400 should NOT match ErrRateLimit or ErrTemporary
+	err = ClassifySendError(400, raw)
+	if errors.Is(err, ErrRateLimit) {
+		t.Error("400 should not match ErrRateLimit")
+	}
+	if errors.Is(err, ErrTemporary) {
+		t.Error("400 should not match ErrTemporary")
+	}
+}
+
+func TestClassifyNetError(t *testing.T) {
+	t.Run("nil error returns nil", func(t *testing.T) {
+		if err := ClassifyNetError(nil); err != nil {
+			t.Errorf("expected nil, got %v", err)
+		}
+	})
+
+	t.Run("non-nil error wraps as ErrTemporary", func(t *testing.T) {
+		raw := fmt.Errorf("connection refused")
+		err := ClassifyNetError(raw)
+		if err == nil {
+			t.Fatal("expected non-nil error")
+		}
+		if !errors.Is(err, ErrTemporary) {
+			t.Errorf("errors.Is(err, ErrTemporary) = false, want true; err = %v", err)
+		}
+	})
+}
@@ -0,0 +1,9 @@
+package feishu
+
+// stringValue safely dereferences a *string pointer.
+func stringValue(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return *v
+}
@@ -1,18 +1,19 @@
 //go:build !amd64 && !arm64 && !riscv64 && !mips64 && !ppc64

-package channels
+package feishu

 import (
 	"context"
 	"errors"

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

 // FeishuChannel is a stub implementation for 32-bit architectures
 type FeishuChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 }

 // NewFeishuChannel returns an error on 32-bit architectures where the Feishu SDK is not supported
@@ -1,6 +1,6 @@
 //go:build amd64 || arm64 || riscv64 || mips64 || ppc64

-package channels
+package feishu

 import (
 	"context"
@@ -15,13 +15,15 @@ import (
 	larkws "github.com/larksuite/oapi-sdk-go/v3/ws"

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

 type FeishuChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config   config.FeishuConfig
 	client   *lark.Client
 	wsClient *larkws.Client
@@ -31,7 +33,10 @@ type FeishuChannel struct {
 }

 func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) {
-	base := NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("feishu", cfg, bus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &FeishuChannel{
 		BaseChannel: base,
@@ -60,7 +65,7 @@ func (c *FeishuChannel) Start(ctx context.Context) error {
 	wsClient := c.wsClient
 	c.mu.Unlock()

-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("feishu", "Feishu channel started (websocket mode)")

 	go func() {
@@ -83,14 +88,14 @@ func (c *FeishuChannel) Stop(ctx context.Context) error {
 	c.wsClient = nil
 	c.mu.Unlock()

-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("feishu", "Feishu channel stopped")
 	return nil
 }

 func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("feishu channel not running")
+		return channels.ErrNotRunning
 	}

 	if msg.ChatID == "" {
@@ -114,11 +119,11 @@ func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error

 	resp, err := c.client.Im.V1.Message.Create(ctx, req)
 	if err != nil {
-		return fmt.Errorf("failed to send feishu message: %w", err)
+		return fmt.Errorf("feishu send: %w", channels.ErrTemporary)
 	}

 	if !resp.Success() {
-		return fmt.Errorf("feishu api error: code=%d msg=%s", resp.Code, resp.Msg)
+		return fmt.Errorf("feishu api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
 	}

 	logger.DebugCF("feishu", "Feishu message sent", map[string]any{
@@ -128,7 +133,7 @@ func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 	return nil
 }

-func (c *FeishuChannel) handleMessageReceive(_ context.Context, event *larkim.P2MessageReceiveV1) error {
+func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
 	if event == nil || event.Event == nil || event.Event.Message == nil {
 		return nil
 	}
@@ -152,8 +157,9 @@ func (c *FeishuChannel) handleMessageReceive(_ context.Context, event *larkim.P2
 	}

 	metadata := map[string]string{}
-	if messageID := stringValue(message.MessageId); messageID != "" {
-		metadata["message_id"] = messageID
+	messageID := ""
+	if mid := stringValue(message.MessageId); mid != "" {
+		messageID = mid
 	}
 	if messageType := stringValue(message.MessageType); messageType != "" {
 		metadata["message_type"] = messageType
@@ -166,12 +172,17 @@ func (c *FeishuChannel) handleMessageReceive(_ context.Context, event *larkim.P2
 	}

 	chatType := stringValue(message.ChatType)
+	var peer bus.Peer
 	if chatType == "p2p" {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	} else {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = chatID
+		peer = bus.Peer{Kind: "group", ID: chatID}
+		// In group chats, apply unified group trigger filtering
+		respond, cleaned := c.ShouldRespondInGroup(false, content)
+		if !respond {
+			return nil
+		}
+		content = cleaned
 	}

 	logger.InfoCF("feishu", "Feishu message received", map[string]any{
@@ -180,7 +191,17 @@ func (c *FeishuChannel) handleMessageReceive(_ context.Context, event *larkim.P2
 		"preview":   utils.Truncate(content, 80),
 	})

-	c.HandleMessage(senderID, chatID, content, nil, metadata)
+	senderInfo := bus.SenderInfo{
+		Platform:    "feishu",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("feishu", senderID),
+	}
+
+	if !c.IsAllowedSender(senderInfo) {
+		return nil
+	}
+
+	c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, nil, metadata, senderInfo)
 	return nil
 }

@@ -218,10 +239,3 @@ func extractFeishuMessageContent(message *larkim.EventMessage) string {

 	return *message.Content
 }
-
-func stringValue(v *string) string {
-	if v == nil {
-		return ""
-	}
-	return *v
-}
@@ -0,0 +1,13 @@
+package feishu
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("feishu", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewFeishuChannel(cfg.Channels.Feishu, b)
+	})
+}
@@ -0,0 +1,41 @@
+package channels
+
+import "context"
+
+// TypingCapable — channels that can show a typing/thinking indicator.
+// StartTyping begins the indicator and returns a stop function.
+// The stop function MUST be idempotent and safe to call multiple times.
+type TypingCapable interface {
+	StartTyping(ctx context.Context, chatID string) (stop func(), err error)
+}
+
+// MessageEditor — channels that can edit an existing message.
+// messageID is always string; channels convert platform-specific types internally.
+type MessageEditor interface {
+	EditMessage(ctx context.Context, chatID string, messageID string, content string) error
+}
+
+// ReactionCapable — channels that can add a reaction (e.g. 👀) to an inbound message.
+// ReactToMessage adds a reaction and returns an undo function to remove it.
+// The undo function MUST be idempotent and safe to call multiple times.
+type ReactionCapable interface {
+	ReactToMessage(ctx context.Context, chatID, messageID string) (undo func(), err error)
+}
+
+// PlaceholderCapable — channels that can send a placeholder message
+// (e.g. "Thinking... 💭") that will later be edited to the actual response.
+// The channel MUST also implement MessageEditor for the placeholder to be useful.
+// SendPlaceholder returns the platform message ID of the placeholder so that
+// Manager.preSend can later edit it via MessageEditor.EditMessage.
+type PlaceholderCapable interface {
+	SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
+}
+
+// PlaceholderRecorder is injected into channels by Manager.
+// Channels call these methods on inbound to register typing/placeholder state.
+// Manager uses the registered state on outbound to stop typing and edit placeholders.
+type PlaceholderRecorder interface {
+	RecordPlaceholder(channel, chatID, placeholderID string)
+	RecordTypingStop(channel, chatID string, stop func())
+	RecordReactionUndo(channel, chatID string, undo func())
+}
@@ -0,0 +1,13 @@
+package line
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("line", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewLINEChannel(cfg.Channels.LINE, b)
+	})
+}
@@ -1,4 +1,4 @@
-package channels
+package line

 import (
 	"bytes"
@@ -10,14 +10,16 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"os"
 	"strings"
 	"sync"
 	"time"

 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"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"
 )

@@ -41,14 +43,15 @@ type replyTokenEntry struct {
 // using the LINE Messaging API with HTTP webhook for receiving messages
 // and REST API for sending messages.
 type LINEChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config         config.LINEConfig
-	httpServer     *http.Server
-	botUserID      string   // Bot's user ID
-	botBasicID     string   // Bot's basic ID (e.g. @216ru...)
-	botDisplayName string   // Bot's display name for text-based mention detection
-	replyTokens    sync.Map // chatID -> replyTokenEntry
-	quoteTokens    sync.Map // chatID -> quoteToken (string)
+	infoClient     *http.Client // for bot info lookups (short timeout)
+	apiClient      *http.Client // for messaging API calls
+	botUserID      string       // Bot's user ID
+	botBasicID     string       // Bot's basic ID (e.g. @216ru...)
+	botDisplayName string       // Bot's display name for text-based mention detection
+	replyTokens    sync.Map     // chatID -> replyTokenEntry
+	quoteTokens    sync.Map     // chatID -> quoteToken (string)
 	ctx            context.Context
 	cancel         context.CancelFunc
 }
@@ -59,15 +62,21 @@ func NewLINEChannel(cfg config.LINEConfig, messageBus *bus.MessageBus) (*LINECha
 		return nil, fmt.Errorf("line channel_secret and channel_access_token are required")
 	}

-	base := NewBaseChannel("line", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("line", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(5000),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &LINEChannel{
 		BaseChannel: base,
 		config:      cfg,
+		infoClient:  &http.Client{Timeout: 10 * time.Second},
+		apiClient:   &http.Client{Timeout: 30 * time.Second},
 	}, nil
 }

-// Start launches the HTTP webhook server.
+// Start initializes the LINE channel.
 func (c *LINEChannel) Start(ctx context.Context) error {
 	logger.InfoC("line", "Starting LINE channel (Webhook Mode)")

@@ -86,32 +95,7 @@ func (c *LINEChannel) Start(ctx context.Context) error {
 		})
 	}

-	mux := http.NewServeMux()
-	path := c.config.WebhookPath
-	if path == "" {
-		path = "/webhook/line"
-	}
-	mux.HandleFunc(path, c.webhookHandler)
-
-	addr := fmt.Sprintf("%s:%d", c.config.WebhookHost, c.config.WebhookPort)
-	c.httpServer = &http.Server{
-		Addr:    addr,
-		Handler: mux,
-	}
-
-	go func() {
-		logger.InfoCF("line", "LINE webhook server listening", map[string]any{
-			"addr": addr,
-			"path": path,
-		})
-		if err := c.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			logger.ErrorCF("line", "Webhook server error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}()
-
-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("line", "LINE channel started (Webhook Mode)")
 	return nil
 }
@@ -124,8 +108,7 @@ func (c *LINEChannel) fetchBotInfo() error {
 	}
 	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)

-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := c.infoClient.Do(req)
 	if err != nil {
 		return err
 	}
@@ -150,7 +133,7 @@ func (c *LINEChannel) fetchBotInfo() error {
 	return nil
 }

-// Stop gracefully shuts down the HTTP server.
+// Stop gracefully stops the LINE channel.
 func (c *LINEChannel) Stop(ctx context.Context) error {
 	logger.InfoC("line", "Stopping LINE channel")

@@ -158,21 +141,24 @@ func (c *LINEChannel) Stop(ctx context.Context) error {
 		c.cancel()
 	}

-	if c.httpServer != nil {
-		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
-		defer cancel()
-		if err := c.httpServer.Shutdown(shutdownCtx); err != nil {
-			logger.ErrorCF("line", "Webhook server shutdown error", map[string]any{
-				"error": err.Error(),
-			})
-		}
-	}
-
-	c.setRunning(false)
+	c.SetRunning(false)
 	logger.InfoC("line", "LINE channel stopped")
 	return nil
 }

+// WebhookPath returns the path for registering on the shared HTTP server.
+func (c *LINEChannel) WebhookPath() string {
+	if c.config.WebhookPath != "" {
+		return c.config.WebhookPath
+	}
+	return "/webhook/line"
+}
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *LINEChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	c.webhookHandler(w, r)
+}
+
 // webhookHandler handles incoming LINE webhook requests.
 func (c *LINEChannel) webhookHandler(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
@@ -284,14 +270,6 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		return
 	}

-	// In group chats, only respond when the bot is mentioned
-	if isGroup && !c.isBotMentioned(msg) {
-		logger.DebugCF("line", "Ignoring group message without mention", map[string]any{
-			"chat_id": chatID,
-		})
-		return
-	}
-
 	// Store reply token for later use
 	if event.ReplyToken != "" {
 		c.replyTokens.Store(chatID, replyTokenEntry{
@@ -307,18 +285,22 @@ func (c *LINEChannel) processEvent(event lineEvent) {

 	var content string
 	var mediaPaths []string
-	localFiles := []string{}

-	defer func() {
-		for _, file := range localFiles {
-			if err := os.Remove(file); err != nil {
-				logger.DebugCF("line", "Failed to cleanup temp file", map[string]any{
-					"file":  file,
-					"error": err.Error(),
-				})
+	scope := channels.BuildMediaScope("line", chatID, msg.ID)
+
+	// Helper to register a local file with the media store
+	storeMedia := func(localPath, filename string) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "line",
+			}, scope)
+			if err == nil {
+				return ref
 			}
 		}
-	}()
+		return localPath // fallback
+	}

 	switch msg.Type {
 	case "text":
@@ -330,22 +312,19 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 	case "image":
 		localPath := c.downloadContent(msg.ID, "image.jpg")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "image.jpg"))
 			content = "[image]"
 		}
 	case "audio":
 		localPath := c.downloadContent(msg.ID, "audio.m4a")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "audio.m4a"))
 			content = "[audio]"
 		}
 	case "video":
 		localPath := c.downloadContent(msg.ID, "video.mp4")
 		if localPath != "" {
-			localFiles = append(localFiles, localPath)
-			mediaPaths = append(mediaPaths, localPath)
+			mediaPaths = append(mediaPaths, storeMedia(localPath, "video.mp4"))
 			content = "[video]"
 		}
 	case "file":
@@ -360,18 +339,29 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		return
 	}

+	// In group chats, apply unified group trigger filtering
+	if isGroup {
+		isMentioned := c.isBotMentioned(msg)
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			logger.DebugCF("line", "Ignoring group message by group trigger", map[string]any{
+				"chat_id": chatID,
+			})
+			return
+		}
+		content = cleaned
+	}
+
 	metadata := map[string]string{
 		"platform":    "line",
 		"source_type": event.Source.Type,
-		"message_id":  msg.ID,
 	}

+	var peer bus.Peer
 	if isGroup {
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = chatID
+		peer = bus.Peer{Kind: "group", ID: chatID}
 	} else {
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}
 	}

 	logger.DebugCF("line", "Received message", map[string]any{
@@ -382,10 +372,17 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 		"preview":      utils.Truncate(content, 50),
 	})

-	// Show typing/loading indicator (requires user ID, not group ID)
-	c.sendLoading(senderID)
+	sender := bus.SenderInfo{
+		Platform:    "line",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("line", senderID),
+	}

-	c.HandleMessage(senderID, chatID, content, mediaPaths, metadata)
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, mediaPaths, metadata, sender)
 }

 // isBotMentioned checks if the bot is mentioned in the message.
@@ -491,7 +488,7 @@ func (c *LINEChannel) resolveChatID(source lineSource) string {
 // using a cached reply token, then falls back to the Push API.
 func (c *LINEChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("line channel not running")
+		return channels.ErrNotRunning
 	}

 	// Load and consume quote token for this chat
@@ -519,6 +516,36 @@ func (c *LINEChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	return c.sendPush(ctx, msg.ChatID, msg.Content, quoteToken)
 }

+// SendMedia implements the channels.MediaSender interface.
+// LINE requires media to be accessible via public URL; since we only have local files,
+// we fall back to sending a text message with the filename/caption.
+// For full support, an external file hosting service would be needed.
+func (c *LINEChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// LINE Messaging API requires publicly accessible URLs for media messages.
+	// Since we only have local file paths, send caption text as fallback.
+	for _, part := range msg.Parts {
+		caption := part.Caption
+		if caption == "" {
+			caption = fmt.Sprintf("[%s: %s]", part.Type, part.Filename)
+		}
+
+		if err := c.sendPush(ctx, msg.ChatID, caption, ""); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
 // buildTextMessage creates a text message object, optionally with quoteToken.
 func buildTextMessage(content, quoteToken string) map[string]string {
 	msg := map[string]string{
@@ -551,17 +578,58 @@ func (c *LINEChannel) sendPush(ctx context.Context, to, content, quoteToken stri
 	return c.callAPI(ctx, linePushEndpoint, payload)
 }

+// StartTyping implements channels.TypingCapable using LINE's loading animation.
+//
+// NOTE: The LINE loading animation API only works for 1:1 chats.
+// Group/room chat IDs (starting with "C" or "R") are detected automatically;
+// for these, a no-op stop function is returned without calling the API.
+func (c *LINEChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	if chatID == "" {
+		return func() {}, nil
+	}
+
+	// Group/room chats: LINE loading animation is 1:1 only.
+	if strings.HasPrefix(chatID, "C") || strings.HasPrefix(chatID, "R") {
+		return func() {}, nil
+	}
+
+	typingCtx, cancel := context.WithCancel(ctx)
+	var once sync.Once
+	stop := func() { once.Do(cancel) }
+
+	// Send immediately, then refresh periodically for long-running tasks.
+	if err := c.sendLoading(typingCtx, chatID); err != nil {
+		stop()
+		return stop, err
+	}
+
+	ticker := time.NewTicker(50 * time.Second)
+	go func() {
+		defer ticker.Stop()
+		for {
+			select {
+			case <-typingCtx.Done():
+				return
+			case <-ticker.C:
+				if err := c.sendLoading(typingCtx, chatID); err != nil {
+					logger.DebugCF("line", "Failed to refresh loading indicator", map[string]any{
+						"error": err.Error(),
+					})
+				}
+			}
+		}
+	}()
+
+	return stop, nil
+}
+
 // sendLoading sends a loading animation indicator to the chat.
-func (c *LINEChannel) sendLoading(chatID string) {
+func (c *LINEChannel) sendLoading(ctx context.Context, chatID string) error {
 	payload := map[string]any{
 		"chatId":         chatID,
 		"loadingSeconds": 60,
 	}
-	if err := c.callAPI(c.ctx, lineLoadingEndpoint, payload); err != nil {
-		logger.DebugCF("line", "Failed to send loading indicator", map[string]any{
-			"error": err.Error(),
-		})
-	}
+	return c.callAPI(ctx, lineLoadingEndpoint, payload)
 }

 // callAPI makes an authenticated POST request to the LINE API.
@@ -579,16 +647,15 @@ func (c *LINEChannel) callAPI(ctx context.Context, endpoint string, payload any)
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)

-	client := &http.Client{Timeout: 30 * time.Second}
-	resp, err := client.Do(req)
+	resp, err := c.apiClient.Do(req)
 	if err != nil {
-		return fmt.Errorf("API request failed: %w", err)
+		return channels.ClassifyNetError(err)
 	}
 	defer resp.Body.Close()

 	if resp.StatusCode != http.StatusOK {
 		respBody, _ := io.ReadAll(resp.Body)
-		return fmt.Errorf("LINE API error (status %d): %s", resp.StatusCode, string(respBody))
+		return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("LINE API error: %s", string(respBody)))
 	}

 	return nil
@@ -0,0 +1,13 @@
+package maixcam
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("maixcam", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewMaixCamChannel(cfg.Channels.MaixCam, b)
+	})
+}
@@ -1,4 +1,4 @@
-package channels
+package maixcam

 import (
 	"context"
@@ -6,16 +6,21 @@ import (
 	"fmt"
 	"net"
 	"sync"
+	"time"

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

 type MaixCamChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config     config.MaixCamConfig
 	listener   net.Listener
+	ctx        context.Context
+	cancel     context.CancelFunc
 	clients    map[net.Conn]bool
 	clientsMux sync.RWMutex
 }
@@ -28,7 +33,13 @@ type MaixCamMessage struct {
 }

 func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamChannel, error) {
-	base := NewBaseChannel("maixcam", cfg, bus, cfg.AllowFrom)
+	base := channels.NewBaseChannel(
+		"maixcam",
+		cfg,
+		bus,
+		cfg.AllowFrom,
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &MaixCamChannel{
 		BaseChannel: base,
@@ -40,37 +51,40 @@ func NewMaixCamChannel(cfg config.MaixCamConfig, bus *bus.MessageBus) (*MaixCamC
 func (c *MaixCamChannel) Start(ctx context.Context) error {
 	logger.InfoC("maixcam", "Starting MaixCam channel server")

+	c.ctx, c.cancel = context.WithCancel(ctx)
+
 	addr := fmt.Sprintf("%s:%d", c.config.Host, c.config.Port)
 	listener, err := net.Listen("tcp", addr)
 	if err != nil {
+		c.cancel()
 		return fmt.Errorf("failed to listen on %s: %w", addr, err)
 	}

 	c.listener = listener
-	c.setRunning(true)
+	c.SetRunning(true)

 	logger.InfoCF("maixcam", "MaixCam server listening", map[string]any{
 		"host": c.config.Host,
 		"port": c.config.Port,
 	})

-	go c.acceptConnections(ctx)
+	go c.acceptConnections()

 	return nil
 }

-func (c *MaixCamChannel) acceptConnections(ctx context.Context) {
+func (c *MaixCamChannel) acceptConnections() {
 	logger.DebugC("maixcam", "Starting connection acceptor")

 	for {
 		select {
-		case <-ctx.Done():
+		case <-c.ctx.Done():
 			logger.InfoC("maixcam", "Stopping connection acceptor")
 			return
 		default:
 			conn, err := c.listener.Accept()
 			if err != nil {
-				if c.running {
+				if c.IsRunning() {
 					logger.ErrorCF("maixcam", "Failed to accept connection", map[string]any{
 						"error": err.Error(),
 					})
@@ -86,12 +100,12 @@ func (c *MaixCamChannel) acceptConnections(ctx context.Context) {
 			c.clients[conn] = true
 			c.clientsMux.Unlock()

-			go c.handleConnection(conn, ctx)
+			go c.handleConnection(conn)
 		}
 	}
 }

-func (c *MaixCamChannel) handleConnection(conn net.Conn, ctx context.Context) {
+func (c *MaixCamChannel) handleConnection(conn net.Conn) {
 	logger.DebugC("maixcam", "Handling MaixCam connection")

 	defer func() {
@@ -106,7 +120,7 @@ func (c *MaixCamChannel) handleConnection(conn net.Conn, ctx context.Context) {

 	for {
 		select {
-		case <-ctx.Done():
+		case <-c.ctx.Done():
 			return
 		default:
 			var msg MaixCamMessage
@@ -170,11 +184,29 @@ func (c *MaixCamChannel) handlePersonDetection(msg MaixCamMessage) {
 		"y":         fmt.Sprintf("%.0f", y),
 		"w":         fmt.Sprintf("%.0f", w),
 		"h":         fmt.Sprintf("%.0f", h),
-		"peer_kind": "channel",
-		"peer_id":   "default",
 	}

-	c.HandleMessage(senderID, chatID, content, []string{}, metadata)
+	sender := bus.SenderInfo{
+		Platform:    "maixcam",
+		PlatformID:  "maixcam",
+		CanonicalID: identity.BuildCanonicalID("maixcam", "maixcam"),
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(
+		c.ctx,
+		bus.Peer{Kind: "channel", ID: "default"},
+		"",
+		senderID,
+		chatID,
+		content,
+		[]string{},
+		metadata,
+		sender,
+	)
 }

 func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) {
@@ -185,7 +217,12 @@ func (c *MaixCamChannel) handleStatusUpdate(msg MaixCamMessage) {

 func (c *MaixCamChannel) Stop(ctx context.Context) error {
 	logger.InfoC("maixcam", "Stopping MaixCam channel")
-	c.setRunning(false)
+	c.SetRunning(false)
+
+	// Cancel context first to signal goroutines to exit
+	if c.cancel != nil {
+		c.cancel()
+	}

 	if c.listener != nil {
 		c.listener.Close()
@@ -205,7 +242,14 @@ func (c *MaixCamChannel) Stop(ctx context.Context) error {

 func (c *MaixCamChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("maixcam channel not running")
+		return channels.ErrNotRunning
+	}
+
+	// Check ctx before entering write path
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
 	}

 	c.clientsMux.RLock()
@@ -230,13 +274,15 @@ func (c *MaixCamChannel) Send(ctx context.Context, msg bus.OutboundMessage) erro

 	var sendErr error
 	for conn := range c.clients {
+		_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 		if _, err := conn.Write(data); err != nil {
 			logger.ErrorCF("maixcam", "Failed to send to client", map[string]any{
 				"client": conn.RemoteAddr().String(),
 				"error":  err.Error(),
 			})
-			sendErr = err
+			sendErr = fmt.Errorf("maixcam send: %w", channels.ErrTemporary)
 		}
+		_ = conn.SetWriteDeadline(time.Time{})
 	}

 	return sendErr
@@ -8,32 +8,152 @@ package channels

 import (
 	"context"
+	"errors"
 	"fmt"
+	"math"
+	"net/http"
 	"sync"
+	"time"
+
+	"golang.org/x/time/rate"

 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
+	"github.com/sipeed/picoclaw/pkg/health"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 )

+const (
+	defaultChannelQueueSize = 16
+	defaultRateLimit        = 10 // default 10 msg/s
+	maxRetries              = 3
+	rateLimitDelay          = 1 * time.Second
+	baseBackoff             = 500 * time.Millisecond
+	maxBackoff              = 8 * time.Second
+
+	janitorInterval = 10 * time.Second
+	typingStopTTL   = 5 * time.Minute
+	placeholderTTL  = 10 * time.Minute
+)
+
+// typingEntry wraps a typing stop function with a creation timestamp for TTL eviction.
+type typingEntry struct {
+	stop      func()
+	createdAt time.Time
+}
+
+// reactionEntry wraps a reaction undo function with a creation timestamp for TTL eviction.
+type reactionEntry struct {
+	undo      func()
+	createdAt time.Time
+}
+
+// placeholderEntry wraps a placeholder ID with a creation timestamp for TTL eviction.
+type placeholderEntry struct {
+	id        string
+	createdAt time.Time
+}
+
+// channelRateConfig maps channel name to per-second rate limit.
+var channelRateConfig = map[string]float64{
+	"telegram": 20,
+	"discord":  1,
+	"slack":    1,
+	"line":     10,
+}
+
+type channelWorker struct {
+	ch         Channel
+	queue      chan bus.OutboundMessage
+	mediaQueue chan bus.OutboundMediaMessage
+	done       chan struct{}
+	mediaDone  chan struct{}
+	limiter    *rate.Limiter
+}
+
 type Manager struct {
-	channels     map[string]Channel
-	bus          *bus.MessageBus
-	config       *config.Config
-	dispatchTask *asyncTask
-	mu           sync.RWMutex
+	channels      map[string]Channel
+	workers       map[string]*channelWorker
+	bus           *bus.MessageBus
+	config        *config.Config
+	mediaStore    media.MediaStore
+	dispatchTask  *asyncTask
+	mux           *http.ServeMux
+	httpServer    *http.Server
+	mu            sync.RWMutex
+	placeholders  sync.Map // "channel:chatID" → placeholderID (string)
+	typingStops   sync.Map // "channel:chatID" → func()
+	reactionUndos sync.Map // "channel:chatID" → reactionEntry
 }

 type asyncTask struct {
 	cancel context.CancelFunc
 }

-func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error) {
+// RecordPlaceholder registers a placeholder message for later editing.
+// Implements PlaceholderRecorder.
+func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string) {
+	key := channel + ":" + chatID
+	m.placeholders.Store(key, placeholderEntry{id: placeholderID, createdAt: time.Now()})
+}
+
+// RecordTypingStop registers a typing stop function for later invocation.
+// Implements PlaceholderRecorder.
+func (m *Manager) RecordTypingStop(channel, chatID string, stop func()) {
+	key := channel + ":" + chatID
+	m.typingStops.Store(key, typingEntry{stop: stop, createdAt: time.Now()})
+}
+
+// RecordReactionUndo registers a reaction undo function for later invocation.
+// Implements PlaceholderRecorder.
+func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) {
+	key := channel + ":" + chatID
+	m.reactionUndos.Store(key, reactionEntry{undo: undo, createdAt: time.Now()})
+}
+
+// preSend handles typing stop, reaction undo, and placeholder editing before sending a message.
+// Returns true if the message was edited into a placeholder (skip Send).
+func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMessage, ch Channel) bool {
+	key := name + ":" + msg.ChatID
+
+	// 1. Stop typing
+	if v, loaded := m.typingStops.LoadAndDelete(key); loaded {
+		if entry, ok := v.(typingEntry); ok {
+			entry.stop() // idempotent, safe
+		}
+	}
+
+	// 2. Undo reaction
+	if v, loaded := m.reactionUndos.LoadAndDelete(key); loaded {
+		if entry, ok := v.(reactionEntry); ok {
+			entry.undo() // idempotent, safe
+		}
+	}
+
+	// 3. Try editing placeholder
+	if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
+		if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
+			if editor, ok := ch.(MessageEditor); ok {
+				if err := editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content); err == nil {
+					return true // edited successfully, skip Send
+				}
+				// edit failed → fall through to normal Send
+			}
+		}
+	}
+
+	return false
+}
+
+func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.MediaStore) (*Manager, error) {
 	m := &Manager{
-		channels: make(map[string]Channel),
-		bus:      messageBus,
-		config:   cfg,
+		channels:   make(map[string]Channel),
+		workers:    make(map[string]*channelWorker),
+		bus:        messageBus,
+		config:     cfg,
+		mediaStore: store,
 	}

 	if err := m.initChannels(); err != nil {
@@ -43,163 +163,104 @@ func NewManager(cfg *config.Config, messageBus *bus.MessageBus) (*Manager, error
 	return m, nil
 }

+// initChannel is a helper that looks up a factory by name and creates the channel.
+func (m *Manager) initChannel(name, displayName string) {
+	f, ok := getFactory(name)
+	if !ok {
+		logger.WarnCF("channels", "Factory not registered", map[string]any{
+			"channel": displayName,
+		})
+		return
+	}
+	logger.DebugCF("channels", "Attempting to initialize channel", map[string]any{
+		"channel": displayName,
+	})
+	ch, err := f(m.config, m.bus)
+	if err != nil {
+		logger.ErrorCF("channels", "Failed to initialize channel", map[string]any{
+			"channel": displayName,
+			"error":   err.Error(),
+		})
+	} else {
+		// Inject MediaStore if channel supports it
+		if m.mediaStore != nil {
+			if setter, ok := ch.(interface{ SetMediaStore(s media.MediaStore) }); ok {
+				setter.SetMediaStore(m.mediaStore)
+			}
+		}
+		// Inject PlaceholderRecorder if channel supports it
+		if setter, ok := ch.(interface{ SetPlaceholderRecorder(r PlaceholderRecorder) }); ok {
+			setter.SetPlaceholderRecorder(m)
+		}
+		// Inject owner reference so BaseChannel.HandleMessage can auto-trigger typing/reaction
+		if setter, ok := ch.(interface{ SetOwner(ch Channel) }); ok {
+			setter.SetOwner(ch)
+		}
+		m.channels[name] = ch
+		logger.InfoCF("channels", "Channel enabled successfully", map[string]any{
+			"channel": displayName,
+		})
+	}
+}
+
 func (m *Manager) initChannels() error {
 	logger.InfoC("channels", "Initializing channel manager")

 	if m.config.Channels.Telegram.Enabled && m.config.Channels.Telegram.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize Telegram channel")
-		telegram, err := NewTelegramChannel(m.config, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Telegram channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["telegram"] = telegram
-			logger.InfoC("channels", "Telegram channel enabled successfully")
-		}
+		m.initChannel("telegram", "Telegram")
 	}

-	if m.config.Channels.WhatsApp.Enabled && m.config.Channels.WhatsApp.BridgeURL != "" {
-		logger.DebugC("channels", "Attempting to initialize WhatsApp channel")
-		whatsapp, err := NewWhatsAppChannel(m.config.Channels.WhatsApp, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WhatsApp channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["whatsapp"] = whatsapp
-			logger.InfoC("channels", "WhatsApp channel enabled successfully")
+	if m.config.Channels.WhatsApp.Enabled {
+		waCfg := m.config.Channels.WhatsApp
+		if waCfg.UseNative {
+			m.initChannel("whatsapp_native", "WhatsApp Native")
+		} else if waCfg.BridgeURL != "" {
+			m.initChannel("whatsapp", "WhatsApp")
 		}
 	}

 	if m.config.Channels.Feishu.Enabled {
-		logger.DebugC("channels", "Attempting to initialize Feishu channel")
-		feishu, err := NewFeishuChannel(m.config.Channels.Feishu, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Feishu channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["feishu"] = feishu
-			logger.InfoC("channels", "Feishu channel enabled successfully")
-		}
+		m.initChannel("feishu", "Feishu")
 	}

 	if m.config.Channels.Discord.Enabled && m.config.Channels.Discord.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize Discord channel")
-		discord, err := NewDiscordChannel(m.config.Channels.Discord, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Discord channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["discord"] = discord
-			logger.InfoC("channels", "Discord channel enabled successfully")
-		}
+		m.initChannel("discord", "Discord")
 	}

 	if m.config.Channels.MaixCam.Enabled {
-		logger.DebugC("channels", "Attempting to initialize MaixCam channel")
-		maixcam, err := NewMaixCamChannel(m.config.Channels.MaixCam, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize MaixCam channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["maixcam"] = maixcam
-			logger.InfoC("channels", "MaixCam channel enabled successfully")
-		}
+		m.initChannel("maixcam", "MaixCam")
 	}

 	if m.config.Channels.QQ.Enabled {
-		logger.DebugC("channels", "Attempting to initialize QQ channel")
-		qq, err := NewQQChannel(m.config.Channels.QQ, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize QQ channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["qq"] = qq
-			logger.InfoC("channels", "QQ channel enabled successfully")
-		}
+		m.initChannel("qq", "QQ")
 	}

 	if m.config.Channels.DingTalk.Enabled && m.config.Channels.DingTalk.ClientID != "" {
-		logger.DebugC("channels", "Attempting to initialize DingTalk channel")
-		dingtalk, err := NewDingTalkChannel(m.config.Channels.DingTalk, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize DingTalk channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["dingtalk"] = dingtalk
-			logger.InfoC("channels", "DingTalk channel enabled successfully")
-		}
+		m.initChannel("dingtalk", "DingTalk")
 	}

 	if m.config.Channels.Slack.Enabled && m.config.Channels.Slack.BotToken != "" {
-		logger.DebugC("channels", "Attempting to initialize Slack channel")
-		slackCh, err := NewSlackChannel(m.config.Channels.Slack, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize Slack channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["slack"] = slackCh
-			logger.InfoC("channels", "Slack channel enabled successfully")
-		}
+		m.initChannel("slack", "Slack")
 	}

 	if m.config.Channels.LINE.Enabled && m.config.Channels.LINE.ChannelAccessToken != "" {
-		logger.DebugC("channels", "Attempting to initialize LINE channel")
-		line, err := NewLINEChannel(m.config.Channels.LINE, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize LINE channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["line"] = line
-			logger.InfoC("channels", "LINE channel enabled successfully")
-		}
+		m.initChannel("line", "LINE")
 	}

 	if m.config.Channels.OneBot.Enabled && m.config.Channels.OneBot.WSUrl != "" {
-		logger.DebugC("channels", "Attempting to initialize OneBot channel")
-		onebot, err := NewOneBotChannel(m.config.Channels.OneBot, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize OneBot channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["onebot"] = onebot
-			logger.InfoC("channels", "OneBot channel enabled successfully")
-		}
+		m.initChannel("onebot", "OneBot")
 	}

 	if m.config.Channels.WeCom.Enabled && m.config.Channels.WeCom.Token != "" {
-		logger.DebugC("channels", "Attempting to initialize WeCom channel")
-		wecom, err := NewWeComBotChannel(m.config.Channels.WeCom, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WeCom channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["wecom"] = wecom
-			logger.InfoC("channels", "WeCom channel enabled successfully")
-		}
+		m.initChannel("wecom", "WeCom")
 	}

 	if m.config.Channels.WeComApp.Enabled && m.config.Channels.WeComApp.CorpID != "" {
-		logger.DebugC("channels", "Attempting to initialize WeCom App channel")
-		wecomApp, err := NewWeComAppChannel(m.config.Channels.WeComApp, m.bus)
-		if err != nil {
-			logger.ErrorCF("channels", "Failed to initialize WeCom App channel", map[string]any{
-				"error": err.Error(),
-			})
-		} else {
-			m.channels["wecom_app"] = wecomApp
-			logger.InfoC("channels", "WeCom App channel enabled successfully")
-		}
+		m.initChannel("wecom_app", "WeCom App")
+	}
+
+	if m.config.Channels.Pico.Enabled && m.config.Channels.Pico.Token != "" {
+		m.initChannel("pico", "Pico")
 	}

 	logger.InfoCF("channels", "Channel initialization completed", map[string]any{
@@ -209,13 +270,50 @@ func (m *Manager) initChannels() error {
 	return nil
 }

+// SetupHTTPServer creates a shared HTTP server with the given listen address.
+// It registers health endpoints from the health server and discovers channels
+// that implement WebhookHandler and/or HealthChecker to register their handlers.
+func (m *Manager) SetupHTTPServer(addr string, healthServer *health.Server) {
+	m.mux = http.NewServeMux()
+
+	// Register health endpoints
+	if healthServer != nil {
+		healthServer.RegisterOnMux(m.mux)
+	}
+
+	// Discover and register webhook handlers and health checkers
+	for name, ch := range m.channels {
+		if wh, ok := ch.(WebhookHandler); ok {
+			m.mux.Handle(wh.WebhookPath(), wh)
+			logger.InfoCF("channels", "Webhook handler registered", map[string]any{
+				"channel": name,
+				"path":    wh.WebhookPath(),
+			})
+		}
+		if hc, ok := ch.(HealthChecker); ok {
+			m.mux.HandleFunc(hc.HealthPath(), hc.HealthHandler)
+			logger.InfoCF("channels", "Health endpoint registered", map[string]any{
+				"channel": name,
+				"path":    hc.HealthPath(),
+			})
+		}
+	}
+
+	m.httpServer = &http.Server{
+		Addr:         addr,
+		Handler:      m.mux,
+		ReadTimeout:  30 * time.Second,
+		WriteTimeout: 30 * time.Second,
+	}
+}
+
 func (m *Manager) StartAll(ctx context.Context) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()

 	if len(m.channels) == 0 {
 		logger.WarnC("channels", "No channels enabled")
-		return nil
+		return errors.New("no channels enabled")
 	}

 	logger.InfoC("channels", "Starting all channels")
@@ -223,8 +321,6 @@ func (m *Manager) StartAll(ctx context.Context) error {
 	dispatchCtx, cancel := context.WithCancel(ctx)
 	m.dispatchTask = &asyncTask{cancel: cancel}

-	go m.dispatchOutbound(dispatchCtx)
-
 	for name, channel := range m.channels {
 		logger.InfoCF("channels", "Starting channel", map[string]any{
 			"channel": name,
@@ -234,7 +330,34 @@ func (m *Manager) StartAll(ctx context.Context) error {
 				"channel": name,
 				"error":   err.Error(),
 			})
+			continue
 		}
+		// Lazily create worker only after channel starts successfully
+		w := newChannelWorker(name, channel)
+		m.workers[name] = w
+		go m.runWorker(dispatchCtx, name, w)
+		go m.runMediaWorker(dispatchCtx, name, w)
+	}
+
+	// Start the dispatcher that reads from the bus and routes to workers
+	go m.dispatchOutbound(dispatchCtx)
+	go m.dispatchOutboundMedia(dispatchCtx)
+
+	// Start the TTL janitor that cleans up stale typing/placeholder entries
+	go m.runTTLJanitor(dispatchCtx)
+
+	// Start shared HTTP server if configured
+	if m.httpServer != nil {
+		go func() {
+			logger.InfoCF("channels", "Shared HTTP server listening", map[string]any{
+				"addr": m.httpServer.Addr,
+			})
+			if err := m.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+				logger.ErrorCF("channels", "Shared HTTP server error", map[string]any{
+					"error": err.Error(),
+				})
+			}
+		}()
 	}

 	logger.InfoC("channels", "All channels started")
@@ -247,11 +370,48 @@ func (m *Manager) StopAll(ctx context.Context) error {

 	logger.InfoC("channels", "Stopping all channels")

+	// Shutdown shared HTTP server first
+	if m.httpServer != nil {
+		shutdownCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		defer cancel()
+		if err := m.httpServer.Shutdown(shutdownCtx); err != nil {
+			logger.ErrorCF("channels", "Shared HTTP server shutdown error", map[string]any{
+				"error": err.Error(),
+			})
+		}
+		m.httpServer = nil
+	}
+
+	// Cancel dispatcher
 	if m.dispatchTask != nil {
 		m.dispatchTask.cancel()
 		m.dispatchTask = nil
 	}

+	// Close all worker queues and wait for them to drain
+	for _, w := range m.workers {
+		if w != nil {
+			close(w.queue)
+		}
+	}
+	for _, w := range m.workers {
+		if w != nil {
+			<-w.done
+		}
+	}
+	// Close all media worker queues and wait for them to drain
+	for _, w := range m.workers {
+		if w != nil {
+			close(w.mediaQueue)
+		}
+	}
+	for _, w := range m.workers {
+		if w != nil {
+			<-w.mediaDone
+		}
+	}
+
+	// Stop all channels
 	for name, channel := range m.channels {
 		logger.InfoCF("channels", "Stopping channel", map[string]any{
 			"channel": name,
@@ -268,42 +428,316 @@ func (m *Manager) StopAll(ctx context.Context) error {
 	return nil
 }

+// newChannelWorker creates a channelWorker with a rate limiter configured
+// for the given channel name.
+func newChannelWorker(name string, ch Channel) *channelWorker {
+	rateVal := float64(defaultRateLimit)
+	if r, ok := channelRateConfig[name]; ok {
+		rateVal = r
+	}
+	burst := int(math.Max(1, math.Ceil(rateVal/2)))
+
+	return &channelWorker{
+		ch:         ch,
+		queue:      make(chan bus.OutboundMessage, defaultChannelQueueSize),
+		mediaQueue: make(chan bus.OutboundMediaMessage, defaultChannelQueueSize),
+		done:       make(chan struct{}),
+		mediaDone:  make(chan struct{}),
+		limiter:    rate.NewLimiter(rate.Limit(rateVal), burst),
+	}
+}
+
+// runWorker processes outbound messages for a single channel, splitting
+// messages that exceed the channel's maximum message length.
+func (m *Manager) runWorker(ctx context.Context, name string, w *channelWorker) {
+	defer close(w.done)
+	for {
+		select {
+		case msg, ok := <-w.queue:
+			if !ok {
+				return
+			}
+			maxLen := 0
+			if mlp, ok := w.ch.(MessageLengthProvider); ok {
+				maxLen = mlp.MaxMessageLength()
+			}
+			if maxLen > 0 && len([]rune(msg.Content)) > maxLen {
+				chunks := SplitMessage(msg.Content, maxLen)
+				for _, chunk := range chunks {
+					chunkMsg := msg
+					chunkMsg.Content = chunk
+					m.sendWithRetry(ctx, name, w, chunkMsg)
+				}
+			} else {
+				m.sendWithRetry(ctx, name, w, msg)
+			}
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// sendWithRetry sends a message through the channel with rate limiting and
+// retry logic. It classifies errors to determine the retry strategy:
+//   - ErrNotRunning / ErrSendFailed: permanent, no retry
+//   - ErrRateLimit: fixed delay retry
+//   - ErrTemporary / unknown: exponential backoff retry
+func (m *Manager) sendWithRetry(ctx context.Context, name string, w *channelWorker, msg bus.OutboundMessage) {
+	// Rate limit: wait for token
+	if err := w.limiter.Wait(ctx); err != nil {
+		// ctx canceled, shutting down
+		return
+	}
+
+	// Pre-send: stop typing and try to edit placeholder
+	if m.preSend(ctx, name, msg, w.ch) {
+		return // placeholder was edited successfully, skip Send
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		lastErr = w.ch.Send(ctx, msg)
+		if lastErr == nil {
+			return
+		}
+
+		// Permanent failures — don't retry
+		if errors.Is(lastErr, ErrNotRunning) || errors.Is(lastErr, ErrSendFailed) {
+			break
+		}
+
+		// Last attempt exhausted — don't sleep
+		if attempt == maxRetries {
+			break
+		}
+
+		// Rate limit error — fixed delay
+		if errors.Is(lastErr, ErrRateLimit) {
+			select {
+			case <-time.After(rateLimitDelay):
+				continue
+			case <-ctx.Done():
+				return
+			}
+		}
+
+		// ErrTemporary or unknown error — exponential backoff
+		backoff := min(time.Duration(float64(baseBackoff)*math.Pow(2, float64(attempt))), maxBackoff)
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+	}
+
+	// All retries exhausted or permanent failure
+	logger.ErrorCF("channels", "Send failed", map[string]any{
+		"channel": name,
+		"chat_id": msg.ChatID,
+		"error":   lastErr.Error(),
+		"retries": maxRetries,
+	})
+}
+
 func (m *Manager) dispatchOutbound(ctx context.Context) {
 	logger.InfoC("channels", "Outbound dispatcher started")

 	for {
-		select {
-		case <-ctx.Done():
+		msg, ok := m.bus.SubscribeOutbound(ctx)
+		if !ok {
 			logger.InfoC("channels", "Outbound dispatcher stopped")
 			return
-		default:
-			msg, ok := m.bus.SubscribeOutbound(ctx)
+		}
+
+		// Silently skip internal channels
+		if constants.IsInternalChannel(msg.Channel) {
+			continue
+		}
+
+		m.mu.RLock()
+		_, exists := m.channels[msg.Channel]
+		w, wExists := m.workers[msg.Channel]
+		m.mu.RUnlock()
+
+		if !exists {
+			logger.WarnCF("channels", "Unknown channel for outbound message", map[string]any{
+				"channel": msg.Channel,
+			})
+			continue
+		}
+
+		if wExists && w != nil {
+			select {
+			case w.queue <- msg:
+			case <-ctx.Done():
+				return
+			}
+		} else if exists {
+			logger.WarnCF("channels", "Channel has no active worker, skipping message", map[string]any{
+				"channel": msg.Channel,
+			})
+		}
+	}
+}
+
+func (m *Manager) dispatchOutboundMedia(ctx context.Context) {
+	logger.InfoC("channels", "Outbound media dispatcher started")
+
+	for {
+		msg, ok := m.bus.SubscribeOutboundMedia(ctx)
+		if !ok {
+			logger.InfoC("channels", "Outbound media dispatcher stopped")
+			return
+		}
+
+		// Silently skip internal channels
+		if constants.IsInternalChannel(msg.Channel) {
+			continue
+		}
+
+		m.mu.RLock()
+		_, exists := m.channels[msg.Channel]
+		w, wExists := m.workers[msg.Channel]
+		m.mu.RUnlock()
+
+		if !exists {
+			logger.WarnCF("channels", "Unknown channel for outbound media message", map[string]any{
+				"channel": msg.Channel,
+			})
+			continue
+		}
+
+		if wExists && w != nil {
+			select {
+			case w.mediaQueue <- msg:
+			case <-ctx.Done():
+				return
+			}
+		} else if exists {
+			logger.WarnCF("channels", "Channel has no active worker, skipping media message", map[string]any{
+				"channel": msg.Channel,
+			})
+		}
+	}
+}
+
+// runMediaWorker processes outbound media messages for a single channel.
+func (m *Manager) runMediaWorker(ctx context.Context, name string, w *channelWorker) {
+	defer close(w.mediaDone)
+	for {
+		select {
+		case msg, ok := <-w.mediaQueue:
 			if !ok {
+				return
+			}
+			m.sendMediaWithRetry(ctx, name, w, msg)
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+// sendMediaWithRetry sends a media message through the channel with rate limiting and
+// retry logic. If the channel does not implement MediaSender, it silently skips.
+func (m *Manager) sendMediaWithRetry(ctx context.Context, name string, w *channelWorker, msg bus.OutboundMediaMessage) {
+	ms, ok := w.ch.(MediaSender)
+	if !ok {
+		logger.DebugCF("channels", "Channel does not support MediaSender, skipping media", map[string]any{
+			"channel": name,
+		})
+		return
+	}
+
+	// Rate limit: wait for token
+	if err := w.limiter.Wait(ctx); err != nil {
+		return
+	}
+
+	var lastErr error
+	for attempt := 0; attempt <= maxRetries; attempt++ {
+		lastErr = ms.SendMedia(ctx, msg)
+		if lastErr == nil {
+			return
+		}
+
+		// Permanent failures — don't retry
+		if errors.Is(lastErr, ErrNotRunning) || errors.Is(lastErr, ErrSendFailed) {
+			break
+		}
+
+		// Last attempt exhausted — don't sleep
+		if attempt == maxRetries {
+			break
+		}
+
+		// Rate limit error — fixed delay
+		if errors.Is(lastErr, ErrRateLimit) {
+			select {
+			case <-time.After(rateLimitDelay):
 				continue
+			case <-ctx.Done():
+				return
 			}
+		}

-			// Silently skip internal channels
-			if constants.IsInternalChannel(msg.Channel) {
-				continue
-			}
+		// ErrTemporary or unknown error — exponential backoff
+		backoff := min(time.Duration(float64(baseBackoff)*math.Pow(2, float64(attempt))), maxBackoff)
+		select {
+		case <-time.After(backoff):
+		case <-ctx.Done():
+			return
+		}
+	}

-			m.mu.RLock()
-			channel, exists := m.channels[msg.Channel]
-			m.mu.RUnlock()
+	// All retries exhausted or permanent failure
+	logger.ErrorCF("channels", "SendMedia failed", map[string]any{
+		"channel": name,
+		"chat_id": msg.ChatID,
+		"error":   lastErr.Error(),
+		"retries": maxRetries,
+	})
+}

-			if !exists {
-				logger.WarnCF("channels", "Unknown channel for outbound message", map[string]any{
-					"channel": msg.Channel,
-				})
-				continue
-			}
+// runTTLJanitor periodically scans the typingStops and placeholders maps
+// and evicts entries that have exceeded their TTL. This prevents memory
+// accumulation when outbound paths fail to trigger preSend (e.g. LLM errors).
+func (m *Manager) runTTLJanitor(ctx context.Context) {
+	ticker := time.NewTicker(janitorInterval)
+	defer ticker.Stop()

-			if err := channel.Send(ctx, msg); err != nil {
-				logger.ErrorCF("channels", "Error sending message to channel", map[string]any{
-					"channel": msg.Channel,
-					"error":   err.Error(),
-				})
-			}
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case now := <-ticker.C:
+			m.typingStops.Range(func(key, value any) bool {
+				if entry, ok := value.(typingEntry); ok {
+					if now.Sub(entry.createdAt) > typingStopTTL {
+						if _, loaded := m.typingStops.LoadAndDelete(key); loaded {
+							entry.stop() // idempotent, safe
+						}
+					}
+				}
+				return true
+			})
+			m.reactionUndos.Range(func(key, value any) bool {
+				if entry, ok := value.(reactionEntry); ok {
+					if now.Sub(entry.createdAt) > typingStopTTL {
+						if _, loaded := m.reactionUndos.LoadAndDelete(key); loaded {
+							entry.undo() // idempotent, safe
+						}
+					}
+				}
+				return true
+			})
+			m.placeholders.Range(func(key, value any) bool {
+				if entry, ok := value.(placeholderEntry); ok {
+					if now.Sub(entry.createdAt) > placeholderTTL {
+						m.placeholders.Delete(key)
+					}
+				}
+				return true
+			})
 		}
 	}
 }
@@ -349,12 +783,20 @@ func (m *Manager) RegisterChannel(name string, channel Channel) {
 func (m *Manager) UnregisterChannel(name string) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
+	if w, ok := m.workers[name]; ok && w != nil {
+		close(w.queue)
+		<-w.done
+		close(w.mediaQueue)
+		<-w.mediaDone
+	}
+	delete(m.workers, name)
 	delete(m.channels, name)
 }

 func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, content string) error {
 	m.mu.RLock()
-	channel, exists := m.channels[channelName]
+	_, exists := m.channels[channelName]
+	w, wExists := m.workers[channelName]
 	m.mu.RUnlock()

 	if !exists {
@@ -367,5 +809,16 @@ func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, conten
 		Content: content,
 	}

+	if wExists && w != nil {
+		select {
+		case w.queue <- msg:
+			return nil
+		case <-ctx.Done():
+			return ctx.Err()
+		}
+	}
+
+	// Fallback: direct send (should not happen)
+	channel, _ := m.channels[channelName]
 	return channel.Send(ctx, msg)
 }
@@ -0,0 +1,862 @@
+package channels
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"golang.org/x/time/rate"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// mockChannel is a test double that delegates Send to a configurable function.
+type mockChannel struct {
+	BaseChannel
+	sendFn func(ctx context.Context, msg bus.OutboundMessage) error
+}
+
+func (m *mockChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	return m.sendFn(ctx, msg)
+}
+
+func (m *mockChannel) Start(ctx context.Context) error { return nil }
+func (m *mockChannel) Stop(ctx context.Context) error  { return nil }
+
+// newTestManager creates a minimal Manager suitable for unit tests.
+func newTestManager() *Manager {
+	return &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+	}
+}
+
+func TestSendWithRetry_Success(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call, got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_TemporaryThenSuccess(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount <= 2 {
+				return fmt.Errorf("network error: %w", ErrTemporary)
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 3 {
+		t.Fatalf("expected 3 Send calls (2 failures + 1 success), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_PermanentFailure(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("bad chat ID: %w", ErrSendFailed)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call (no retry for permanent failure), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_NotRunning(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return ErrNotRunning
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call (no retry for ErrNotRunning), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_RateLimitRetry(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount == 1 {
+				return fmt.Errorf("429: %w", ErrRateLimit)
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	start := time.Now()
+	m.sendWithRetry(ctx, "test", w, msg)
+	elapsed := time.Since(start)
+
+	if callCount != 2 {
+		t.Fatalf("expected 2 Send calls (1 rate limit + 1 success), got %d", callCount)
+	}
+	// Should have waited at least rateLimitDelay (1s) but allow some slack
+	if elapsed < 900*time.Millisecond {
+		t.Fatalf("expected at least ~1s delay for rate limit retry, got %v", elapsed)
+	}
+}
+
+func TestSendWithRetry_MaxRetriesExhausted(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	expected := maxRetries + 1 // initial attempt + maxRetries retries
+	if callCount != expected {
+		t.Fatalf("expected %d Send calls, got %d", expected, callCount)
+	}
+}
+
+func TestSendWithRetry_UnknownError(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount == 1 {
+				return errors.New("random unexpected error")
+			}
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	if callCount != 2 {
+		t.Fatalf("expected 2 Send calls (unknown error treated as temporary), got %d", callCount)
+	}
+}
+
+func TestSendWithRetry_ContextCancelled(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	// Cancel context after first Send attempt returns
+	ch.sendFn = func(_ context.Context, _ bus.OutboundMessage) error {
+		callCount++
+		cancel()
+		return fmt.Errorf("timeout: %w", ErrTemporary)
+	}
+
+	m.sendWithRetry(ctx, "test", w, msg)
+
+	// Should have called Send once, then noticed ctx canceled during backoff
+	if callCount != 1 {
+		t.Fatalf("expected 1 Send call before context cancellation, got %d", callCount)
+	}
+}
+
+func TestWorkerRateLimiter(t *testing.T) {
+	m := newTestManager()
+
+	var mu sync.Mutex
+	var sendTimes []time.Time
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			mu.Lock()
+			sendTimes = append(sendTimes, time.Now())
+			mu.Unlock()
+			return nil
+		},
+	}
+
+	// Create a worker with a low rate: 2 msg/s, burst 1
+	w := &channelWorker{
+		ch:      ch,
+		queue:   make(chan bus.OutboundMessage, 10),
+		done:    make(chan struct{}),
+		limiter: rate.NewLimiter(2, 1),
+	}
+
+	ctx := t.Context()
+
+	go m.runWorker(ctx, "test", w)
+
+	// Enqueue 4 messages
+	for i := range 4 {
+		w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: fmt.Sprintf("msg%d", i)}
+	}
+
+	// Wait enough time for all messages to be sent (4 msgs at 2/s = ~2s, give extra margin)
+	time.Sleep(3 * time.Second)
+
+	mu.Lock()
+	times := make([]time.Time, len(sendTimes))
+	copy(times, sendTimes)
+	mu.Unlock()
+
+	if len(times) != 4 {
+		t.Fatalf("expected 4 sends, got %d", len(times))
+	}
+
+	// Verify rate limiting: total duration should be at least 1s
+	// (first message immediate, then ~500ms between each subsequent one at 2/s)
+	totalDuration := times[len(times)-1].Sub(times[0])
+	if totalDuration < 1*time.Second {
+		t.Fatalf("expected total duration >= 1s for 4 msgs at 2/s rate, got %v", totalDuration)
+	}
+}
+
+func TestNewChannelWorker_DefaultRate(t *testing.T) {
+	ch := &mockChannel{}
+	w := newChannelWorker("unknown_channel", ch)
+
+	if w.limiter == nil {
+		t.Fatal("expected limiter to be non-nil")
+	}
+	if w.limiter.Limit() != rate.Limit(defaultRateLimit) {
+		t.Fatalf("expected rate limit %v, got %v", rate.Limit(defaultRateLimit), w.limiter.Limit())
+	}
+}
+
+func TestNewChannelWorker_ConfiguredRate(t *testing.T) {
+	ch := &mockChannel{}
+
+	for name, expectedRate := range channelRateConfig {
+		w := newChannelWorker(name, ch)
+		if w.limiter.Limit() != rate.Limit(expectedRate) {
+			t.Fatalf("channel %s: expected rate %v, got %v", name, expectedRate, w.limiter.Limit())
+		}
+	}
+}
+
+func TestRunWorker_MessageSplitting(t *testing.T) {
+	m := newTestManager()
+
+	var mu sync.Mutex
+	var received []string
+
+	ch := &mockChannelWithLength{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+				mu.Lock()
+				received = append(received, msg.Content)
+				mu.Unlock()
+				return nil
+			},
+		},
+		maxLen: 5,
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		queue:   make(chan bus.OutboundMessage, 10),
+		done:    make(chan struct{}),
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := t.Context()
+
+	go m.runWorker(ctx, "test", w)
+
+	// Send a message that should be split
+	w.queue <- bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello world"}
+
+	time.Sleep(100 * time.Millisecond)
+
+	mu.Lock()
+	count := len(received)
+	mu.Unlock()
+
+	if count < 2 {
+		t.Fatalf("expected message to be split into at least 2 chunks, got %d", count)
+	}
+}
+
+// mockChannelWithLength implements MessageLengthProvider.
+type mockChannelWithLength struct {
+	mockChannel
+	maxLen int
+}
+
+func (m *mockChannelWithLength) MaxMessageLength() int {
+	return m.maxLen
+}
+
+func TestSendWithRetry_ExponentialBackoff(t *testing.T) {
+	m := newTestManager()
+
+	var callTimes []time.Time
+	var callCount atomic.Int32
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callTimes = append(callTimes, time.Now())
+			callCount.Add(1)
+			return fmt.Errorf("timeout: %w", ErrTemporary)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	ctx := context.Background()
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "1", Content: "hello"}
+
+	start := time.Now()
+	m.sendWithRetry(ctx, "test", w, msg)
+	totalElapsed := time.Since(start)
+
+	// With maxRetries=3: attempts at 0, ~500ms, ~1.5s, ~3.5s
+	// Total backoff: 500ms + 1s + 2s = 3.5s
+	// Allow some margin
+	if totalElapsed < 3*time.Second {
+		t.Fatalf("expected total elapsed >= 3s for exponential backoff, got %v", totalElapsed)
+	}
+
+	if int(callCount.Load()) != maxRetries+1 {
+		t.Fatalf("expected %d calls, got %d", maxRetries+1, callCount.Load())
+	}
+}
+
+// --- Phase 10: preSend orchestration tests ---
+
+// mockMessageEditor is a channel that supports MessageEditor.
+type mockMessageEditor struct {
+	mockChannel
+	editFn func(ctx context.Context, chatID, messageID, content string) error
+}
+
+func (m *mockMessageEditor) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+	return m.editFn(ctx, chatID, messageID, content)
+}
+
+func TestPreSend_PlaceholderEditSuccess(t *testing.T) {
+	m := newTestManager()
+	var sendCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				sendCalled = true
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, chatID, messageID, content string) error {
+			editCalled = true
+			if chatID != "123" {
+				t.Fatalf("expected chatID 123, got %s", chatID)
+			}
+			if messageID != "456" {
+				t.Fatalf("expected messageID 456, got %s", messageID)
+			}
+			if content != "hello" {
+				t.Fatalf("expected content 'hello', got %s", content)
+			}
+			return nil
+		},
+	}
+
+	// Register placeholder
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !edited {
+		t.Fatal("expected preSend to return true (placeholder edited)")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called")
+	}
+	if sendCalled {
+		t.Fatal("expected Send to NOT be called when placeholder edited")
+	}
+}
+
+func TestPreSend_PlaceholderEditFails_FallsThrough(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			return fmt.Errorf("edit failed")
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if edited {
+		t.Fatal("expected preSend to return false when edit fails")
+	}
+}
+
+func TestPreSend_TypingStopCalled(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	m.RecordTypingStop("test", "123", func() {
+		stopCalled = true
+	})
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop func to be called")
+	}
+}
+
+func TestPreSend_NoRegisteredState(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if edited {
+		t.Fatal("expected preSend to return false with no registered state")
+	}
+}
+
+func TestPreSend_TypingAndPlaceholder(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			editCalled = true
+			return nil
+		},
+	}
+
+	m.RecordTypingStop("test", "123", func() {
+		stopCalled = true
+	})
+	m.RecordPlaceholder("test", "123", "456")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop to be called")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called")
+	}
+	if !edited {
+		t.Fatal("expected preSend to return true")
+	}
+}
+
+func TestRecordPlaceholder_ConcurrentSafe(t *testing.T) {
+	m := newTestManager()
+
+	var wg sync.WaitGroup
+	for i := range 100 {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			chatID := fmt.Sprintf("chat_%d", i%10)
+			m.RecordPlaceholder("test", chatID, fmt.Sprintf("msg_%d", i))
+		}(i)
+	}
+	wg.Wait()
+}
+
+func TestRecordTypingStop_ConcurrentSafe(t *testing.T) {
+	m := newTestManager()
+
+	var wg sync.WaitGroup
+	for i := range 100 {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			chatID := fmt.Sprintf("chat_%d", i%10)
+			m.RecordTypingStop("test", chatID, func() {})
+		}(i)
+	}
+	wg.Wait()
+}
+
+func TestSendWithRetry_PreSendEditsPlaceholder(t *testing.T) {
+	m := newTestManager()
+	var sendCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				sendCalled = true
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, _, _, _ string) error {
+			return nil // edit succeeds
+		},
+	}
+
+	m.RecordPlaceholder("test", "123", "456")
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	m.sendWithRetry(context.Background(), "test", w, msg)
+
+	if sendCalled {
+		t.Fatal("expected Send to NOT be called when placeholder was edited")
+	}
+}
+
+// --- Dispatcher exit tests (Step 1) ---
+
+func TestDispatcherExitsOnCancel(t *testing.T) {
+	mb := bus.NewMessageBus()
+	defer mb.Close()
+
+	m := &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+		bus:      mb,
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+
+	go func() {
+		m.dispatchOutbound(ctx)
+		close(done)
+	}()
+
+	// Cancel context and verify the dispatcher exits quickly
+	cancel()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatchOutbound did not exit within 2s after context cancel")
+	}
+}
+
+func TestDispatcherMediaExitsOnCancel(t *testing.T) {
+	mb := bus.NewMessageBus()
+	defer mb.Close()
+
+	m := &Manager{
+		channels: make(map[string]Channel),
+		workers:  make(map[string]*channelWorker),
+		bus:      mb,
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+
+	go func() {
+		m.dispatchOutboundMedia(ctx)
+		close(done)
+	}()
+
+	cancel()
+
+	select {
+	case <-done:
+		// success
+	case <-time.After(2 * time.Second):
+		t.Fatal("dispatchOutboundMedia did not exit within 2s after context cancel")
+	}
+}
+
+// --- TTL Janitor tests (Step 2) ---
+
+func TestTypingStopJanitorEviction(t *testing.T) {
+	m := newTestManager()
+
+	var stopCalled atomic.Bool
+	// Store a typing entry with a creation time far in the past
+	m.typingStops.Store("test:123", typingEntry{
+		stop:      func() { stopCalled.Store(true) },
+		createdAt: time.Now().Add(-10 * time.Minute), // well past typingStopTTL
+	})
+
+	// Run janitor with a short-lived context
+	ctx, cancel := context.WithCancel(context.Background())
+
+	// Manually trigger the janitor logic once by simulating a tick
+	go func() {
+		// Override janitor to run immediately
+		now := time.Now()
+		m.typingStops.Range(func(key, value any) bool {
+			if entry, ok := value.(typingEntry); ok {
+				if now.Sub(entry.createdAt) > typingStopTTL {
+					if _, loaded := m.typingStops.LoadAndDelete(key); loaded {
+						entry.stop()
+					}
+				}
+			}
+			return true
+		})
+		cancel()
+	}()
+
+	<-ctx.Done()
+
+	if !stopCalled.Load() {
+		t.Fatal("expected typing stop function to be called by janitor eviction")
+	}
+
+	// Verify entry was deleted
+	if _, loaded := m.typingStops.Load("test:123"); loaded {
+		t.Fatal("expected typing entry to be deleted after eviction")
+	}
+}
+
+func TestPlaceholderJanitorEviction(t *testing.T) {
+	m := newTestManager()
+
+	// Store a placeholder entry with a creation time far in the past
+	m.placeholders.Store("test:456", placeholderEntry{
+		id:        "msg_old",
+		createdAt: time.Now().Add(-20 * time.Minute), // well past placeholderTTL
+	})
+
+	// Simulate janitor logic
+	now := time.Now()
+	m.placeholders.Range(func(key, value any) bool {
+		if entry, ok := value.(placeholderEntry); ok {
+			if now.Sub(entry.createdAt) > placeholderTTL {
+				m.placeholders.Delete(key)
+			}
+		}
+		return true
+	})
+
+	// Verify entry was deleted
+	if _, loaded := m.placeholders.Load("test:456"); loaded {
+		t.Fatal("expected placeholder entry to be deleted after eviction")
+	}
+}
+
+func TestPreSendStillWorksWithWrappedTypes(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+	var editCalled bool
+
+	ch := &mockMessageEditor{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+				return nil
+			},
+		},
+		editFn: func(_ context.Context, chatID, messageID, content string) error {
+			editCalled = true
+			if messageID != "ph_id" {
+				t.Fatalf("expected messageID ph_id, got %s", messageID)
+			}
+			return nil
+		},
+	}
+
+	// Use the new wrapped types via the public API
+	m.RecordTypingStop("test", "chat1", func() {
+		stopCalled = true
+	})
+	m.RecordPlaceholder("test", "chat1", "ph_id")
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "chat1", Content: "response"}
+	edited := m.preSend(context.Background(), "test", msg, ch)
+
+	if !stopCalled {
+		t.Fatal("expected typing stop to be called via wrapped type")
+	}
+	if !editCalled {
+		t.Fatal("expected EditMessage to be called via wrapped type")
+	}
+	if !edited {
+		t.Fatal("expected preSend to return true")
+	}
+}
+
+// --- Lazy worker creation tests (Step 6) ---
+
+func TestLazyWorkerCreation(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+
+	// RegisterChannel should NOT create a worker
+	m.RegisterChannel("lazy", ch)
+
+	m.mu.RLock()
+	_, chExists := m.channels["lazy"]
+	_, wExists := m.workers["lazy"]
+	m.mu.RUnlock()
+
+	if !chExists {
+		t.Fatal("expected channel to be registered")
+	}
+	if wExists {
+		t.Fatal("expected worker to NOT be created by RegisterChannel (lazy creation)")
+	}
+}
+
+// --- FastID uniqueness test (Step 5) ---
+
+func TestBuildMediaScope_FastIDUniqueness(t *testing.T) {
+	seen := make(map[string]bool)
+
+	for range 1000 {
+		scope := BuildMediaScope("test", "chat1", "")
+		if seen[scope] {
+			t.Fatalf("duplicate scope generated: %s", scope)
+		}
+		seen[scope] = true
+	}
+
+	// Verify format: "channel:chatID:id"
+	scope := BuildMediaScope("telegram", "42", "")
+	parts := 0
+	for _, c := range scope {
+		if c == ':' {
+			parts++
+		}
+	}
+	if parts != 2 {
+		t.Fatalf("expected scope to have 2 colons (channel:chatID:id), got: %s", scope)
+	}
+}
+
+func TestBuildMediaScope_WithMessageID(t *testing.T) {
+	scope := BuildMediaScope("discord", "chat99", "msg123")
+	expected := "discord:chat99:msg123"
+	if scope != expected {
+		t.Fatalf("expected %s, got %s", expected, scope)
+	}
+}
@@ -0,0 +1,15 @@
+package channels
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+)
+
+// MediaSender is an optional interface for channels that can send
+// media attachments (images, files, audio, video).
+// Manager discovers channels implementing this interface via type
+// assertion and routes OutboundMediaMessage to them.
+type MediaSender interface {
+	SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error
+}
@@ -0,0 +1,13 @@
+package onebot
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("onebot", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewOneBotChannel(cfg.Channels.OneBot, b)
+	})
+}
@@ -1,10 +1,9 @@
-package channels
+package onebot

 import (
 	"context"
 	"encoding/json"
 	"fmt"
-	"os"
 	"strconv"
 	"strings"
 	"sync"
@@ -14,30 +13,30 @@ import (
 	"github.com/gorilla/websocket"

 	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
 	"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"
-	"github.com/sipeed/picoclaw/pkg/voice"
 )

 type OneBotChannel struct {
-	*BaseChannel
-	config          config.OneBotConfig
-	conn            *websocket.Conn
-	ctx             context.Context
-	cancel          context.CancelFunc
-	dedup           map[string]struct{}
-	dedupRing       []string
-	dedupIdx        int
-	mu              sync.Mutex
-	writeMu         sync.Mutex
-	echoCounter     int64
-	selfID          int64
-	pending         map[string]chan json.RawMessage
-	pendingMu       sync.Mutex
-	transcriber     *voice.GroqTranscriber
-	lastMessageID   sync.Map
-	pendingEmojiMsg sync.Map
+	*channels.BaseChannel
+	config        config.OneBotConfig
+	conn          *websocket.Conn
+	ctx           context.Context
+	cancel        context.CancelFunc
+	dedup         map[string]struct{}
+	dedupRing     []string
+	dedupIdx      int
+	mu            sync.Mutex
+	writeMu       sync.Mutex
+	echoCounter   int64
+	selfID        int64
+	pending       map[string]chan json.RawMessage
+	pendingMu     sync.Mutex
+	lastMessageID sync.Map
 }

 type oneBotRawEvent struct {
@@ -98,7 +97,10 @@ type oneBotMessageSegment struct {
 }

 func NewOneBotChannel(cfg config.OneBotConfig, messageBus *bus.MessageBus) (*OneBotChannel, error) {
-	base := NewBaseChannel("onebot", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("onebot", cfg, messageBus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	const dedupSize = 1024
 	return &OneBotChannel{
@@ -111,10 +113,6 @@ func NewOneBotChannel(cfg config.OneBotConfig, messageBus *bus.MessageBus) (*One
 	}, nil
 }

-func (c *OneBotChannel) SetTranscriber(transcriber *voice.GroqTranscriber) {
-	c.transcriber = transcriber
-}
-
 func (c *OneBotChannel) setMsgEmojiLike(messageID string, emojiID int, set bool) {
 	go func() {
 		_, err := c.sendAPIRequest("set_msg_emoji_like", map[string]any{
@@ -131,6 +129,22 @@ func (c *OneBotChannel) setMsgEmojiLike(messageID string, emojiID int, set bool)
 	}()
 }

+// ReactToMessage implements channels.ReactionCapable.
+// It adds an emoji reaction (ID 289) to group messages and returns an undo function.
+// Private messages return a no-op since reactions are only meaningful in groups.
+func (c *OneBotChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	// Only react in group chats
+	if !strings.HasPrefix(chatID, "group:") {
+		return func() {}, nil
+	}
+
+	c.setMsgEmojiLike(messageID, 289, true)
+
+	return func() {
+		c.setMsgEmojiLike(messageID, 289, false)
+	}, nil
+}
+
 func (c *OneBotChannel) Start(ctx context.Context) error {
 	if c.config.WSUrl == "" {
 		return fmt.Errorf("OneBot ws_url not configured")
@@ -159,7 +173,7 @@ func (c *OneBotChannel) Start(ctx context.Context) error {
 		}
 	}

-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("onebot", "OneBot channel started successfully")

 	return nil
@@ -300,7 +314,9 @@ func (c *OneBotChannel) sendAPIRequest(action string, params any, timeout time.D
 	}

 	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
 	c.writeMu.Unlock()

 	if err != nil {
@@ -309,6 +325,9 @@ func (c *OneBotChannel) sendAPIRequest(action string, params any, timeout time.D

 	select {
 	case resp := <-ch:
+		if resp == nil {
+			return nil, fmt.Errorf("API request %s: channel stopped", action)
+		}
 		return resp, nil
 	case <-time.After(timeout):
 		return nil, fmt.Errorf("API request %s timed out after %v", action, timeout)
@@ -318,10 +337,7 @@ func (c *OneBotChannel) sendAPIRequest(action string, params any, timeout time.D
 }

 func (c *OneBotChannel) reconnectLoop() {
-	interval := time.Duration(c.config.ReconnectInterval) * time.Second
-	if interval < 5*time.Second {
-		interval = 5 * time.Second
-	}
+	interval := max(time.Duration(c.config.ReconnectInterval)*time.Second, 5*time.Second)

 	for {
 		select {
@@ -349,7 +365,7 @@ func (c *OneBotChannel) reconnectLoop() {

 func (c *OneBotChannel) Stop(ctx context.Context) error {
 	logger.InfoC("onebot", "Stopping OneBot channel")
-	c.setRunning(false)
+	c.SetRunning(false)

 	if c.cancel != nil {
 		c.cancel()
@@ -357,7 +373,10 @@ func (c *OneBotChannel) Stop(ctx context.Context) error {

 	c.pendingMu.Lock()
 	for echo, ch := range c.pending {
-		close(ch)
+		select {
+		case ch <- nil: // non-blocking wake for blocked sendAPIRequest goroutines
+		default:
+		}
 		delete(c.pending, echo)
 	}
 	c.pendingMu.Unlock()
@@ -374,7 +393,14 @@ func (c *OneBotChannel) Stop(ctx context.Context) error {

 func (c *OneBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("OneBot channel not running")
+		return channels.ErrNotRunning
+	}
+
+	// Check ctx before entering write path
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
 	}

 	c.mu.Lock()
@@ -404,20 +430,127 @@ func (c *OneBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 	}

 	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
 	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
 	c.writeMu.Unlock()

 	if err != nil {
 		logger.ErrorCF("onebot", "Failed to send message", map[string]any{
 			"error": err.Error(),
 		})
-		return err
+		return fmt.Errorf("onebot send: %w", channels.ErrTemporary)
 	}

-	if msgID, ok := c.pendingEmojiMsg.LoadAndDelete(msg.ChatID); ok {
-		if mid, ok := msgID.(string); ok && mid != "" {
-			c.setMsgEmojiLike(mid, 289, false)
+	return nil
+}
+
+// SendMedia implements the channels.MediaSender interface.
+func (c *OneBotChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+	}
+
+	c.mu.Lock()
+	conn := c.conn
+	c.mu.Unlock()
+
+	if conn == nil {
+		return fmt.Errorf("OneBot WebSocket not connected")
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	// Build media segments
+	var segments []oneBotMessageSegment
+	for _, part := range msg.Parts {
+		localPath, err := store.Resolve(part.Ref)
+		if err != nil {
+			logger.ErrorCF("onebot", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
 		}
+
+		var segType string
+		switch part.Type {
+		case "image":
+			segType = "image"
+		case "video":
+			segType = "video"
+		case "audio":
+			segType = "record"
+		default:
+			segType = "file"
+		}
+
+		segments = append(segments, oneBotMessageSegment{
+			Type: segType,
+			Data: map[string]any{"file": "file://" + localPath},
+		})
+
+		if part.Caption != "" {
+			segments = append(segments, oneBotMessageSegment{
+				Type: "text",
+				Data: map[string]any{"text": part.Caption},
+			})
+		}
+	}
+
+	if len(segments) == 0 {
+		return nil
+	}
+
+	chatID := msg.ChatID
+	var action, idKey string
+	var rawID string
+	if rest, ok := strings.CutPrefix(chatID, "group:"); ok {
+		action, idKey, rawID = "send_group_msg", "group_id", rest
+	} else if rest, ok := strings.CutPrefix(chatID, "private:"); ok {
+		action, idKey, rawID = "send_private_msg", "user_id", rest
+	} else {
+		action, idKey, rawID = "send_private_msg", "user_id", chatID
+	}
+
+	id, err := strconv.ParseInt(rawID, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid %s in chatID: %s: %w", idKey, chatID, channels.ErrSendFailed)
+	}
+
+	echo := fmt.Sprintf("send_%d", atomic.AddInt64(&c.echoCounter, 1))
+
+	req := oneBotAPIRequest{
+		Action: action,
+		Params: map[string]any{idKey: id, "message": segments},
+		Echo:   echo,
+	}
+
+	data, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("failed to marshal OneBot request: %w", err)
+	}
+
+	c.writeMu.Lock()
+	_ = conn.SetWriteDeadline(time.Now().Add(10 * time.Second))
+	err = conn.WriteMessage(websocket.TextMessage, data)
+	_ = conn.SetWriteDeadline(time.Time{})
+	c.writeMu.Unlock()
+
+	if err != nil {
+		logger.ErrorCF("onebot", "Failed to send media message", map[string]any{
+			"error": err.Error(),
+		})
+		return fmt.Errorf("onebot send media: %w", channels.ErrTemporary)
 	}

 	return nil
@@ -574,11 +707,15 @@ type parseMessageResult struct {
 	Text           string
 	IsBotMentioned bool
 	Media          []string
-	LocalFiles     []string
 	ReplyTo        string
 }

-func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64) parseMessageResult {
+func (c *OneBotChannel) parseMessageSegments(
+	raw json.RawMessage,
+	selfID int64,
+	store media.MediaStore,
+	scope string,
+) parseMessageResult {
 	if len(raw) == 0 {
 		return parseMessageResult{}
 	}
@@ -605,10 +742,23 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 	var textParts []string
 	mentioned := false
 	selfIDStr := strconv.FormatInt(selfID, 10)
-	var media []string
-	var localFiles []string
+	var mediaRefs []string
 	var replyTo string

+	// Helper to register a local file with the media store
+	storeFile := func(localPath, filename string) string {
+		if store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename: filename,
+				Source:   "onebot",
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath // fallback
+	}
+
 	for _, seg := range segments {
 		segType, _ := seg["type"].(string)
 		data, _ := seg["data"].(map[string]any)
@@ -644,8 +794,7 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						media = append(media, localPath)
-						localFiles = append(localFiles, localPath)
+						mediaRefs = append(mediaRefs, storeFile(localPath, filename))
 						textParts = append(textParts, fmt.Sprintf("[%s]", segType))
 					}
 				}
@@ -659,24 +808,8 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 						LoggerPrefix: "onebot",
 					})
 					if localPath != "" {
-						localFiles = append(localFiles, localPath)
-						if c.transcriber != nil && c.transcriber.IsAvailable() {
-							tctx, tcancel := context.WithTimeout(c.ctx, 30*time.Second)
-							result, err := c.transcriber.Transcribe(tctx, localPath)
-							tcancel()
-							if err != nil {
-								logger.WarnCF("onebot", "Voice transcription failed", map[string]any{
-									"error": err.Error(),
-								})
-								textParts = append(textParts, "[voice (transcription failed)]")
-								media = append(media, localPath)
-							} else {
-								textParts = append(textParts, fmt.Sprintf("[voice transcription: %s]", result.Text))
-							}
-						} else {
-							textParts = append(textParts, "[voice]")
-							media = append(media, localPath)
-						}
+						textParts = append(textParts, "[voice]")
+						mediaRefs = append(mediaRefs, storeFile(localPath, "voice.amr"))
 					}
 				}
 			}
@@ -704,8 +837,7 @@ func (c *OneBotChannel) parseMessageSegments(raw json.RawMessage, selfID int64)
 	return parseMessageResult{
 		Text:           strings.TrimSpace(strings.Join(textParts, "")),
 		IsBotMentioned: mentioned,
-		Media:          media,
-		LocalFiles:     localFiles,
+		Media:          mediaRefs,
 		ReplyTo:        replyTo,
 	}
 }
@@ -714,7 +846,13 @@ func (c *OneBotChannel) handleRawEvent(raw *oneBotRawEvent) {
 	switch raw.PostType {
 	case "message":
 		if userID, err := parseJSONInt64(raw.UserID); err == nil && userID > 0 {
-			if !c.IsAllowed(strconv.FormatInt(userID, 10)) {
+			// Build minimal sender for allowlist check
+			sender := bus.SenderInfo{
+				Platform:    "onebot",
+				PlatformID:  strconv.FormatInt(userID, 10),
+				CanonicalID: identity.BuildCanonicalID("onebot", strconv.FormatInt(userID, 10)),
+			}
+			if !c.IsAllowedSender(sender) {
 				logger.DebugCF("onebot", "Message rejected by allowlist", map[string]any{
 					"user_id": userID,
 				})
@@ -797,7 +935,17 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		selfID = atomic.LoadInt64(&c.selfID)
 	}

-	parsed := c.parseMessageSegments(raw.Message, selfID)
+	// Compute scope for media store before parsing (parsing may download files)
+	var chatIDForScope string
+	switch raw.MessageType {
+	case "group":
+		chatIDForScope = "group:" + strconv.FormatInt(groupID, 10)
+	default:
+		chatIDForScope = "private:" + strconv.FormatInt(userID, 10)
+	}
+	scope := channels.BuildMediaScope("onebot", chatIDForScope, messageID)
+
+	parsed := c.parseMessageSegments(raw.Message, selfID, c.GetMediaStore(), scope)
 	isBotMentioned := parsed.IsBotMentioned

 	content := raw.RawMessage
@@ -826,20 +974,6 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 		}
 	}

-	// Clean up temp files when done
-	if len(parsed.LocalFiles) > 0 {
-		defer func() {
-			for _, f := range parsed.LocalFiles {
-				if err := os.Remove(f); err != nil {
-					logger.DebugCF("onebot", "Failed to remove temp file", map[string]any{
-						"path":  f,
-						"error": err.Error(),
-					})
-				}
-			}
-		}()
-	}
-
 	if c.isDuplicate(messageID) {
 		logger.DebugCF("onebot", "Duplicate message, skipping", map[string]any{
 			"message_id": messageID,
@@ -857,9 +991,9 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 	senderID := strconv.FormatInt(userID, 10)
 	var chatID string

-	metadata := map[string]string{
-		"message_id": messageID,
-	}
+	var peer bus.Peer
+
+	metadata := map[string]string{}

 	if parsed.ReplyTo != "" {
 		metadata["reply_to_message_id"] = parsed.ReplyTo
@@ -868,14 +1002,12 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 	switch raw.MessageType {
 	case "private":
 		chatID = "private:" + senderID
-		metadata["peer_kind"] = "direct"
-		metadata["peer_id"] = senderID
+		peer = bus.Peer{Kind: "direct", ID: senderID}

 	case "group":
 		groupIDStr := strconv.FormatInt(groupID, 10)
 		chatID = "group:" + groupIDStr
-		metadata["peer_kind"] = "group"
-		metadata["peer_id"] = groupIDStr
+		peer = bus.Peer{Kind: "group", ID: groupIDStr}
 		metadata["group_id"] = groupIDStr

 		senderUserID, _ := parseJSONInt64(sender.UserID)
@@ -889,8 +1021,8 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {
 			metadata["sender_name"] = sender.Nickname
 		}

-		triggered, strippedContent := c.checkGroupTrigger(content, isBotMentioned)
-		if !triggered {
+		respond, strippedContent := c.ShouldRespondInGroup(isBotMentioned, content)
+		if !respond {
 			logger.DebugCF("onebot", "Group message ignored (no trigger)", map[string]any{
 				"sender":       senderID,
 				"group":        groupIDStr,
@@ -925,12 +1057,21 @@ func (c *OneBotChannel) handleMessage(raw *oneBotRawEvent) {

 	c.lastMessageID.Store(chatID, messageID)

-	if raw.MessageType == "group" && messageID != "" && messageID != "0" {
-		c.setMsgEmojiLike(messageID, 289, true)
-		c.pendingEmojiMsg.Store(chatID, messageID)
+	senderInfo := bus.SenderInfo{
+		Platform:    "onebot",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("onebot", senderID),
+		DisplayName: sender.Nickname,
 	}

-	c.HandleMessage(senderID, chatID, content, parsed.Media, metadata)
+	if !c.IsAllowedSender(senderInfo) {
+		logger.DebugCF("onebot", "Message rejected by allowlist (senderInfo)", map[string]any{
+			"sender": senderID,
+		})
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, messageID, senderID, chatID, content, parsed.Media, metadata, senderInfo)
 }

 func (c *OneBotChannel) isDuplicate(messageID string) bool {
@@ -962,23 +1103,3 @@ func truncate(s string, n int) string {
 	}
 	return string(runes[:n]) + "..."
 }
-
-func (c *OneBotChannel) checkGroupTrigger(
-	content string,
-	isBotMentioned bool,
-) (triggered bool, strippedContent string) {
-	if isBotMentioned {
-		return true, strings.TrimSpace(content)
-	}
-
-	for _, prefix := range c.config.GroupTriggerPrefix {
-		if prefix == "" {
-			continue
-		}
-		if strings.HasPrefix(content, prefix) {
-			return true, strings.TrimSpace(strings.TrimPrefix(content, prefix))
-		}
-	}
-
-	return false, content
-}
@@ -0,0 +1,13 @@
+package pico
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("pico", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewPicoChannel(cfg.Channels.Pico, b)
+	})
+}
@@ -0,0 +1,462 @@
+package pico
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/gorilla/websocket"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// picoConn represents a single WebSocket connection.
+type picoConn struct {
+	id        string
+	conn      *websocket.Conn
+	sessionID string
+	writeMu   sync.Mutex
+	closed    atomic.Bool
+}
+
+// writeJSON sends a JSON message to the connection with write locking.
+func (pc *picoConn) writeJSON(v any) error {
+	if pc.closed.Load() {
+		return fmt.Errorf("connection closed")
+	}
+	pc.writeMu.Lock()
+	defer pc.writeMu.Unlock()
+	return pc.conn.WriteJSON(v)
+}
+
+// close closes the connection.
+func (pc *picoConn) close() {
+	if pc.closed.CompareAndSwap(false, true) {
+		pc.conn.Close()
+	}
+}
+
+// PicoChannel implements the native Pico Protocol WebSocket channel.
+// It serves as the reference implementation for all optional capability interfaces.
+type PicoChannel struct {
+	*channels.BaseChannel
+	config      config.PicoConfig
+	upgrader    websocket.Upgrader
+	connections sync.Map // connID → *picoConn
+	connCount   atomic.Int32
+	ctx         context.Context
+	cancel      context.CancelFunc
+}
+
+// NewPicoChannel creates a new Pico Protocol channel.
+func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoChannel, error) {
+	if cfg.Token == "" {
+		return nil, fmt.Errorf("pico token is required")
+	}
+
+	base := channels.NewBaseChannel("pico", cfg, messageBus, cfg.AllowFrom)
+
+	allowOrigins := cfg.AllowOrigins
+	checkOrigin := func(r *http.Request) bool {
+		if len(allowOrigins) == 0 {
+			return true // allow all if not configured
+		}
+		origin := r.Header.Get("Origin")
+		for _, allowed := range allowOrigins {
+			if allowed == "*" || allowed == origin {
+				return true
+			}
+		}
+		return false
+	}
+
+	return &PicoChannel{
+		BaseChannel: base,
+		config:      cfg,
+		upgrader: websocket.Upgrader{
+			CheckOrigin:     checkOrigin,
+			ReadBufferSize:  1024,
+			WriteBufferSize: 1024,
+		},
+	}, nil
+}
+
+// Start implements Channel.
+func (c *PicoChannel) Start(ctx context.Context) error {
+	logger.InfoC("pico", "Starting Pico Protocol channel")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+	c.SetRunning(true)
+	logger.InfoC("pico", "Pico Protocol channel started")
+	return nil
+}
+
+// Stop implements Channel.
+func (c *PicoChannel) Stop(ctx context.Context) error {
+	logger.InfoC("pico", "Stopping Pico Protocol channel")
+	c.SetRunning(false)
+
+	// Close all connections
+	c.connections.Range(func(key, value any) bool {
+		if pc, ok := value.(*picoConn); ok {
+			pc.close()
+		}
+		c.connections.Delete(key)
+		return true
+	})
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	logger.InfoC("pico", "Pico Protocol channel stopped")
+	return nil
+}
+
+// WebhookPath implements channels.WebhookHandler.
+func (c *PicoChannel) WebhookPath() string { return "/pico/" }
+
+// ServeHTTP implements http.Handler for the shared HTTP server.
+func (c *PicoChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	path := strings.TrimPrefix(r.URL.Path, "/pico")
+
+	switch {
+	case path == "/ws" || path == "/ws/":
+		c.handleWebSocket(w, r)
+	default:
+		http.NotFound(w, r)
+	}
+}
+
+// Send implements Channel — sends a message to the appropriate WebSocket connection.
+func (c *PicoChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	outMsg := newMessage(TypeMessageCreate, map[string]any{
+		"content": msg.Content,
+	})
+
+	return c.broadcastToSession(msg.ChatID, outMsg)
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *PicoChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	outMsg := newMessage(TypeMessageUpdate, map[string]any{
+		"message_id": messageID,
+		"content":    content,
+	})
+	return c.broadcastToSession(chatID, outMsg)
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *PicoChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	startMsg := newMessage(TypeTypingStart, nil)
+	if err := c.broadcastToSession(chatID, startMsg); err != nil {
+		return func() {}, err
+	}
+	return func() {
+		stopMsg := newMessage(TypeTypingStop, nil)
+		c.broadcastToSession(chatID, stopMsg)
+	}, nil
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+// It sends a placeholder message via the Pico Protocol that will later be
+// edited to the actual response via EditMessage (channels.MessageEditor).
+func (c *PicoChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		return "", nil
+	}
+
+	text := c.config.Placeholder.Text
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	msgID := uuid.New().String()
+	outMsg := newMessage(TypeMessageCreate, map[string]any{
+		"content":    text,
+		"message_id": msgID,
+	})
+
+	if err := c.broadcastToSession(chatID, outMsg); err != nil {
+		return "", err
+	}
+
+	return msgID, nil
+}
+
+// broadcastToSession sends a message to all connections with a matching session.
+func (c *PicoChannel) broadcastToSession(chatID string, msg PicoMessage) error {
+	// chatID format: "pico:<sessionID>"
+	sessionID := strings.TrimPrefix(chatID, "pico:")
+	msg.SessionID = sessionID
+
+	var sent bool
+	c.connections.Range(func(key, value any) bool {
+		pc, ok := value.(*picoConn)
+		if !ok {
+			return true
+		}
+		if pc.sessionID == sessionID {
+			if err := pc.writeJSON(msg); err != nil {
+				logger.DebugCF("pico", "Write to connection failed", map[string]any{
+					"conn_id": pc.id,
+					"error":   err.Error(),
+				})
+			} else {
+				sent = true
+			}
+		}
+		return true
+	})
+
+	if !sent {
+		return fmt.Errorf("no active connections for session %s: %w", sessionID, channels.ErrSendFailed)
+	}
+	return nil
+}
+
+// handleWebSocket upgrades the HTTP connection and manages the WebSocket lifecycle.
+func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
+	if !c.IsRunning() {
+		http.Error(w, "channel not running", http.StatusServiceUnavailable)
+		return
+	}
+
+	// Authenticate
+	if !c.authenticate(r) {
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
+		return
+	}
+
+	// Check connection limit
+	maxConns := c.config.MaxConnections
+	if maxConns <= 0 {
+		maxConns = 100
+	}
+	if int(c.connCount.Load()) >= maxConns {
+		http.Error(w, "too many connections", http.StatusServiceUnavailable)
+		return
+	}
+
+	conn, err := c.upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		logger.ErrorCF("pico", "WebSocket upgrade failed", map[string]any{
+			"error": err.Error(),
+		})
+		return
+	}
+
+	// Determine session ID from query param or generate one
+	sessionID := r.URL.Query().Get("session_id")
+	if sessionID == "" {
+		sessionID = uuid.New().String()
+	}
+
+	pc := &picoConn{
+		id:        uuid.New().String(),
+		conn:      conn,
+		sessionID: sessionID,
+	}
+
+	c.connections.Store(pc.id, pc)
+	c.connCount.Add(1)
+
+	logger.InfoCF("pico", "WebSocket client connected", map[string]any{
+		"conn_id":    pc.id,
+		"session_id": sessionID,
+	})
+
+	go c.readLoop(pc)
+}
+
+// authenticate checks the Bearer token from the Authorization header.
+// Query parameter authentication is only allowed when AllowTokenQuery is explicitly enabled.
+func (c *PicoChannel) authenticate(r *http.Request) bool {
+	token := c.config.Token
+	if token == "" {
+		return false
+	}
+
+	// Check Authorization header
+	auth := r.Header.Get("Authorization")
+	if after, ok := strings.CutPrefix(auth, "Bearer "); ok {
+		if after == token {
+			return true
+		}
+	}
+
+	// Check query parameter only when explicitly allowed
+	if c.config.AllowTokenQuery {
+		if r.URL.Query().Get("token") == token {
+			return true
+		}
+	}
+
+	return false
+}
+
+// readLoop reads messages from a WebSocket connection.
+func (c *PicoChannel) readLoop(pc *picoConn) {
+	defer func() {
+		pc.close()
+		c.connections.Delete(pc.id)
+		c.connCount.Add(-1)
+		logger.InfoCF("pico", "WebSocket client disconnected", map[string]any{
+			"conn_id":    pc.id,
+			"session_id": pc.sessionID,
+		})
+	}()
+
+	readTimeout := time.Duration(c.config.ReadTimeout) * time.Second
+	if readTimeout <= 0 {
+		readTimeout = 60 * time.Second
+	}
+
+	_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+	pc.conn.SetPongHandler(func(appData string) error {
+		_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+		return nil
+	})
+
+	// Start ping ticker
+	pingInterval := time.Duration(c.config.PingInterval) * time.Second
+	if pingInterval <= 0 {
+		pingInterval = 30 * time.Second
+	}
+	go c.pingLoop(pc, pingInterval)
+
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		default:
+		}
+
+		_, rawMsg, err := pc.conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				logger.DebugCF("pico", "WebSocket read error", map[string]any{
+					"conn_id": pc.id,
+					"error":   err.Error(),
+				})
+			}
+			return
+		}
+
+		_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+
+		var msg PicoMessage
+		if err := json.Unmarshal(rawMsg, &msg); err != nil {
+			errMsg := newError("invalid_message", "failed to parse message")
+			pc.writeJSON(errMsg)
+			continue
+		}
+
+		c.handleMessage(pc, msg)
+	}
+}
+
+// pingLoop sends periodic ping frames to keep the connection alive.
+func (c *PicoChannel) pingLoop(pc *picoConn, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		case <-ticker.C:
+			if pc.closed.Load() {
+				return
+			}
+			pc.writeMu.Lock()
+			err := pc.conn.WriteMessage(websocket.PingMessage, nil)
+			pc.writeMu.Unlock()
+			if err != nil {
+				return
+			}
+		}
+	}
+}
+
+// handleMessage processes an inbound Pico Protocol message.
+func (c *PicoChannel) handleMessage(pc *picoConn, msg PicoMessage) {
+	switch msg.Type {
+	case TypePing:
+		pong := newMessage(TypePong, nil)
+		pong.ID = msg.ID
+		pc.writeJSON(pong)
+
+	case TypeMessageSend:
+		c.handleMessageSend(pc, msg)
+
+	default:
+		errMsg := newError("unknown_type", fmt.Sprintf("unknown message type: %s", msg.Type))
+		pc.writeJSON(errMsg)
+	}
+}
+
+// handleMessageSend processes an inbound message.send from a client.
+func (c *PicoChannel) handleMessageSend(pc *picoConn, msg PicoMessage) {
+	content, _ := msg.Payload["content"].(string)
+	if strings.TrimSpace(content) == "" {
+		errMsg := newError("empty_content", "message content is empty")
+		pc.writeJSON(errMsg)
+		return
+	}
+
+	sessionID := msg.SessionID
+	if sessionID == "" {
+		sessionID = pc.sessionID
+	}
+
+	chatID := "pico:" + sessionID
+	senderID := "pico-user"
+
+	peer := bus.Peer{Kind: "direct", ID: "pico:" + sessionID}
+
+	metadata := map[string]string{
+		"platform":   "pico",
+		"session_id": sessionID,
+		"conn_id":    pc.id,
+	}
+
+	logger.DebugCF("pico", "Received message", map[string]any{
+		"session_id": sessionID,
+		"preview":    truncate(content, 50),
+	})
+
+	sender := bus.SenderInfo{
+		Platform:    "pico",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("pico", senderID),
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, nil, metadata, sender)
+}
+
+// truncate truncates a string to maxLen runes.
+func truncate(s string, maxLen int) string {
+	runes := []rune(s)
+	if len(runes) <= maxLen {
+		return s
+	}
+	return string(runes[:maxLen]) + "..."
+}
@@ -0,0 +1,46 @@
+package pico
+
+import "time"
+
+// Protocol message types.
+const (
+	// TypeMessageSend is sent from client to server.
+	TypeMessageSend = "message.send"
+	TypeMediaSend   = "media.send"
+	TypePing        = "ping"
+
+	// TypeMessageCreate is sent from server to client.
+	TypeMessageCreate = "message.create"
+	TypeMessageUpdate = "message.update"
+	TypeMediaCreate   = "media.create"
+	TypeTypingStart   = "typing.start"
+	TypeTypingStop    = "typing.stop"
+	TypeError         = "error"
+	TypePong          = "pong"
+)
+
+// PicoMessage is the wire format for all Pico Protocol messages.
+type PicoMessage struct {
+	Type      string         `json:"type"`
+	ID        string         `json:"id,omitempty"`
+	SessionID string         `json:"session_id,omitempty"`
+	Timestamp int64          `json:"timestamp,omitempty"`
+	Payload   map[string]any `json:"payload,omitempty"`
+}
+
+// newMessage creates a PicoMessage with the given type and payload.
+func newMessage(msgType string, payload map[string]any) PicoMessage {
+	return PicoMessage{
+		Type:      msgType,
+		Timestamp: time.Now().UnixMilli(),
+		Payload:   payload,
+	}
+}
+
+// newError creates an error PicoMessage.
+func newError(code, message string) PicoMessage {
+	return newMessage(TypeError, map[string]any{
+		"code":    code,
+		"message": message,
+	})
+}
@@ -0,0 +1,13 @@
+package qq
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("qq", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewQQChannel(cfg.Channels.QQ, b)
+	})
+}
@@ -1,4 +1,4 @@
-package channels
+package qq

 import (
 	"context"
@@ -14,12 +14,14 @@ import (
 	"golang.org/x/oauth2"

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

 type QQChannel struct {
-	*BaseChannel
+	*channels.BaseChannel
 	config         config.QQConfig
 	api            openapi.OpenAPI
 	tokenSource    oauth2.TokenSource
@@ -31,7 +33,10 @@ type QQChannel struct {
 }

 func NewQQChannel(cfg config.QQConfig, messageBus *bus.MessageBus) (*QQChannel, error) {
-	base := NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom)
+	base := channels.NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom,
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)

 	return &QQChannel{
 		BaseChannel:  base,
@@ -90,11 +95,11 @@ func (c *QQChannel) Start(ctx context.Context) error {
 			logger.ErrorCF("qq", "WebSocket session error", map[string]any{
 				"error": err.Error(),
 			})
-			c.setRunning(false)
+			c.SetRunning(false)
 		}
 	}()

-	c.setRunning(true)
+	c.SetRunning(true)
 	logger.InfoC("qq", "QQ bot started successfully")

 	return nil
@@ -102,7 +107,7 @@ func (c *QQChannel) Start(ctx context.Context) error {

 func (c *QQChannel) Stop(ctx context.Context) error {
 	logger.InfoC("qq", "Stopping QQ bot")
-	c.setRunning(false)
+	c.SetRunning(false)

 	if c.cancel != nil {
 		c.cancel()
@@ -113,7 +118,7 @@ func (c *QQChannel) Stop(ctx context.Context) error {

 func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
-		return fmt.Errorf("QQ bot not running")
+		return channels.ErrNotRunning
 	}

 	// construct message
@@ -127,7 +132,7 @@ func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 		logger.ErrorCF("qq", "Failed to send C2C message", map[string]any{
 			"error": err.Error(),
 		})
-		return err
+		return fmt.Errorf("qq send: %w", channels.ErrTemporary)
 	}

 	return nil
@@ -162,20 +167,35 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			"length": len(content),
 		})

-		// forward to message bus
-		metadata := map[string]string{
-			"message_id": data.ID,
-			"peer_kind":  "direct",
-			"peer_id":    senderID,
+		// 转发到消息总线
+		metadata := map[string]string{}
+
+		sender := bus.SenderInfo{
+			Platform:    "qq",
+			PlatformID:  data.Author.ID,
+			CanonicalID: identity.BuildCanonicalID("qq", data.Author.ID),
 		}

-		c.HandleMessage(senderID, senderID, content, []string{}, metadata)
+		if !c.IsAllowedSender(sender) {
+			return nil
+		}
+
+		c.HandleMessage(c.ctx,
+			bus.Peer{Kind: "direct", ID: senderID},
+			data.ID,
+			senderID,
+			senderID,
+			content,
+			[]string{},
+			metadata,
+			sender,
+		)

 		return nil
 	}
 }

-// handleGroupATMessage handles group @messages
+// handleGroupATMessage handles QQ group @ messages
 func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 	return func(event *dto.WSPayload, data *dto.WSGroupATMessageData) error {
 		// deduplication check
@@ -192,34 +212,57 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			return nil
 		}

-		// extract message content (remove @bot part)
+		// extract message content (remove @ bot part)
 		content := data.Content
 		if content == "" {
 			logger.DebugC("qq", "Received empty group message, ignoring")
 			return nil
 		}

+		// GroupAT event means bot is always mentioned; apply group trigger filtering
+		respond, cleaned := c.ShouldRespondInGroup(true, content)
+		if !respond {
+			return nil
+		}
+		content = cleaned
+
 		logger.InfoCF("qq", "Received group AT message", map[string]any{
 			"sender": senderID,
 			"group":  data.GroupID,
 			"length": len(content),
 		})

-		// forward to message bus (use GroupID as ChatID)
+		// 转发到消息总线（使用 GroupID 作为 ChatID）
 		metadata := map[string]string{
-			"message_id": data.ID,
-			"group_id":   data.GroupID,
-			"peer_kind":  "group",
-			"peer_id":    data.GroupID,
+			"group_id": data.GroupID,
 		}

-		c.HandleMessage(senderID, data.GroupID, content, []string{}, metadata)
+		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{},
+			metadata,
+			sender,
+		)

 		return nil
 	}
 }

-// isDuplicate checks if message is duplicate
+// isDuplicate 检查消息是否重复
 func (c *QQChannel) isDuplicate(messageID string) bool {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -230,9 +273,9 @@ func (c *QQChannel) isDuplicate(messageID string) bool {

 	c.processedIDs[messageID] = true

-	// simple cleanup: limit map size
+	// 简单清理：限制 map 大小
 	if len(c.processedIDs) > 10000 {
-		// clear half
+		// 清空一半
 		count := 0
 		for id := range c.processedIDs {
 			if count >= 5000 {
@@ -0,0 +1,32 @@
+package channels
+
+import (
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// ChannelFactory is a constructor function that creates a Channel from config and message bus.
+// Each channel subpackage registers one or more factories via init().
+type ChannelFactory func(cfg *config.Config, bus *bus.MessageBus) (Channel, error)
+
+var (
+	factoriesMu sync.RWMutex
+	factories   = map[string]ChannelFactory{}
+)
+
+// RegisterFactory registers a named channel factory. Called from subpackage init() functions.
+func RegisterFactory(name string, f ChannelFactory) {
+	factoriesMu.Lock()
+	defer factoriesMu.Unlock()
+	factories[name] = f
+}
+
+// getFactory looks up a channel factory by name.
+func getFactory(name string) (ChannelFactory, bool) {
+	factoriesMu.RLock()
+	defer factoriesMu.RUnlock()
+	f, ok := factories[name]
+	return f, ok
+}
--- a/Show More
+++ b/Show More