From 60a7098fd35b12a6893858b705405fcdd251bee9 Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 00:51:27 +0800 Subject: [PATCH 1/6] feat(search): add Baidu Qianfan AI Search provider with i18n docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add BaiduSearchConfig struct and register in WebToolsConfig/defaults - Insert Baidu Search in priority chain: DuckDuckGo > Baidu > GLM Search - Use perplexityTimeout (30s) — Qianfan is LLM-based - Fix response parsing: use references[] field per API spec - Add baidu_search block to config.example.json docs: sync configuration.md and README Documentation table across all languages - Complete truncated configuration.md for fr/ja/pt-br/vi/zh: add Spawn async flow diagram, Providers table, Model Configuration (all vendors, examples, load balancing, migration), Provider Architecture, Scheduled Tasks, and Advanced Topics links - Add Hooks/Steering/SubTurn entries to Documentation table in all 8 READMEs (en/zh/fr/id/it/ja/pt-br/vi), ordered before Troubleshooting - Add Baidu Search row to web search table in all 8 READMEs and tools_configuration.md (en + 5 i18n); zh README reorders search engines with China-friendly options first - Add Matrix channel docs translations (fr/ja/pt-br/vi) - Add Weixin channel to chat-apps.md and all README Channels tables Co-Authored-By: Claude Opus 4.6 --- README.fr.md | 595 +++++++--- README.id.md | 579 +++++++--- README.it.md | 542 ++++++++-- README.ja.md | 489 +++++++-- README.md | 1504 ++++++-------------------- README.pt-br.md | 603 ++++++++--- README.vi.md | 611 ++++++++--- README.zh.md | 410 ++++++- docs/channels/matrix/README.fr.md | 64 ++ docs/channels/matrix/README.ja.md | 64 ++ docs/channels/matrix/README.md | 2 + docs/channels/matrix/README.pt-br.md | 64 ++ docs/channels/matrix/README.vi.md | 64 ++ docs/channels/matrix/README.zh.md | 2 + docs/chat-apps.md | 43 +- docs/configuration.md | 393 +++++++ docs/fr/chat-apps.md | 52 +- docs/fr/configuration.md | 147 ++- docs/fr/tools_configuration.md | 66 +- docs/ja/chat-apps.md | 52 +- docs/ja/configuration.md | 106 ++ docs/ja/tools_configuration.md | 66 +- docs/pt-br/chat-apps.md | 52 +- docs/pt-br/configuration.md | 145 +++ docs/pt-br/tools_configuration.md | 66 +- docs/tools_configuration.md | 25 + docs/vi/chat-apps.md | 52 +- docs/vi/configuration.md | 145 +++ docs/vi/tools_configuration.md | 66 +- docs/zh/chat-apps.md | 32 +- docs/zh/configuration.md | 353 ++++++ docs/zh/tools_configuration.md | 79 +- pkg/agent/loop.go | 26 +- pkg/config/config.go | 22 +- pkg/config/defaults.go | 6 + pkg/tools/web.go | 139 ++- 36 files changed, 5648 insertions(+), 2078 deletions(-) create mode 100644 docs/channels/matrix/README.fr.md create mode 100644 docs/channels/matrix/README.ja.md create mode 100644 docs/channels/matrix/README.pt-br.md create mode 100644 docs/channels/matrix/README.vi.md diff --git a/README.fr.md b/README.fr.md index cbaffc2d11..301456262c 100644 --- a/README.fr.md +++ b/README.fr.md @@ -3,7 +3,7 @@

PicoClaw : Assistant IA Ultra-Efficace en Go

-

Matériel à $10 · <10 Mo de RAM · Démarrage en <1s · 皮皮虾,我们走!

+

Matériel à $10 · 10 Mo de RAM · Démarrage en ms · Let's Go, PicoClaw!

Go Hardware @@ -24,147 +24,138 @@ --- -> **PicoClaw** est un projet open-source indépendant initié par [Sipeed](https://sipeed.com). Il est entièrement écrit en **Go** — ce n'est pas un fork d'OpenClaw, de NanoBot ou de tout autre projet. +> **PicoClaw** est un projet open-source indépendant initié par [Sipeed](https://sipeed.com), entièrement écrit en **Go** à partir de zéro — ce n'est pas un fork d'OpenClaw, de NanoBot ou de tout autre projet. -🦐 **PicoClaw** est un assistant personnel IA ultra-léger inspiré de [NanoBot](https://github.com/HKUDS/nanobot), entièrement réécrit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — où l'agent IA lui-même a piloté l'intégralité de la migration architecturale et de l'optimisation du code. +**PicoClaw** est un assistant personnel IA ultra-léger inspiré de [NanoBot](https://github.com/HKUDS/nanobot). Il a été entièrement reconstruit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — l'Agent IA lui-même a piloté la migration architecturale et l'optimisation du code. + +**Fonctionne sur du matériel à $10 avec <10 Mo de RAM** — c'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini ! -⚡️ **Extrêmement léger :** Fonctionne sur du matériel à seulement **$10** avec **<10 Mo** de RAM. C'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini ! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 SÉCURITÉ & CANAUX OFFICIELS** -> -> * **PAS DE CRYPTO :** PicoClaw n'a **AUCUN** token/jeton officiel. Toute annonce sur `pump.fun` ou d'autres plateformes de trading est une **ARNAQUE**. +> **Avis de sécurité** > -> * **DOMAINE OFFICIEL :** Le **SEUL** site officiel est **[picoclaw.io](https://picoclaw.io)**, et le site de l'entreprise est **[sipeed.com](https://sipeed.com)**. -> * **Attention :** De nombreux domaines `.ai/.org/.com/.net/...` sont enregistrés par des tiers. -> * **Attention :** PicoClaw est en phase de développement précoce et peut présenter des problèmes de sécurité réseau non résolus. Ne déployez pas en environnement de production avant la version v1.0. -> * **Note :** PicoClaw a récemment fusionné de nombreuses PR, ce qui peut entraîner une empreinte mémoire plus importante (10–20 Mo) dans les dernières versions. Nous prévoyons de prioriser l'optimisation des ressources dès que l'ensemble des fonctionnalités sera stabilisé. +> * **PAS DE CRYPTO :** PicoClaw n'a **pas** émis de tokens officiels ni de cryptomonnaie. Toute affirmation sur `pump.fun` ou d'autres plateformes de trading est une **arnaque**. +> * **DOMAINE OFFICIEL :** Le **SEUL** site officiel est **[picoclaw.io](https://picoclaw.io)**, et le site de l'entreprise est **[sipeed.com](https://sipeed.com)** +> * **ATTENTION :** De nombreux domaines `.ai/.org/.com/.net/...` ont été enregistrés par des tiers. Ne leur faites pas confiance. +> * **NOTE :** PicoClaw est en développement rapide précoce. Des problèmes de sécurité non résolus peuvent exister. Ne pas déployer en production avant la v1.0. +> * **NOTE :** PicoClaw a récemment fusionné de nombreuses PRs. Les builds récents peuvent utiliser 10-20 Mo de RAM. L'optimisation des ressources est prévue après la stabilisation des fonctionnalités. ## 📢 Actualités -2026-03-17 🚀 **v0.2.3 publié !** Interface système tray (Windows & Linux), suivi de statut des sous-agents (`spawn_status`), rechargement à chaud expérimental du gateway, portes de sécurité cron, et 2 correctifs de sécurité. PicoClaw atteint **25K ⭐** ! +2026-03-17 🚀 **v0.2.3 publiée !** Interface system tray (Windows & Linux), requête de statut des sous-agents (`spawn_status`), rechargement à chaud expérimental du Gateway, sécurisation Cron, et 2 correctifs de sécurité. PicoClaw a atteint **25K Stars** ! -2026-03-09 🎉 **v0.2.1 — Plus grande mise à jour !** Support du protocole MCP, 4 nouveaux canaux (Matrix/IRC/WeCom/Discord Proxy), 3 nouveaux fournisseurs (Kimi/Minimax/Avian), pipeline de vision, stockage mémoire JSONL, et routage de modèles. +2026-03-09 🎉 **v0.2.1 — La plus grande mise à jour à ce jour !** Support du protocole MCP, 4 nouveaux channels (Matrix/IRC/WeCom/Discord Proxy), 3 nouveaux providers (Kimi/Minimax/Avian), pipeline vision, stockage mémoire JSONL, routage de modèles. -2026-02-28 📦 **v0.2.0** publié avec support Docker Compose et lanceur Web UI. +2026-02-28 📦 **v0.2.0** publiée avec support Docker Compose et Web UI Launcher. -2026-02-26 🎉 PicoClaw a atteint **20K étoiles** en seulement 17 jours ! L'orchestration automatique des canaux et les interfaces de capacités sont arrivées. +2026-02-26 🎉 PicoClaw atteint **20K Stars** en seulement 17 jours ! L'orchestration automatique des channels et les interfaces de capacités sont disponibles.

Actualités précédentes... -2026-02-16 🎉 PicoClaw a atteint 12K étoiles en une semaine ! Les rôles de mainteneurs communautaires et la [feuille de route](ROADMAP.md) sont officiellement publiés. +2026-02-16 🎉 PicoClaw dépasse 12K Stars en une semaine ! Rôles de mainteneurs communautaires et [Roadmap](ROADMAP.md) officiellement lancés. -2026-02-13 🎉 PicoClaw a atteint 5000 étoiles en 4 jours ! La Feuille de Route du Projet et le Groupe de Développeurs sont en cours de mise en place. +2026-02-13 🎉 PicoClaw dépasse 5000 Stars en 4 jours ! Roadmap du projet et groupes de développeurs en cours. -2026-02-09 🎉 **PicoClaw est lancé !** Construit en 1 jour pour apporter les Agents IA au matériel à $10 avec <10 Mo de RAM. 🦐 PicoClaw, c'est parti ! +2026-02-09 🎉 **PicoClaw publié !** Construit en 1 jour pour apporter les Agents IA sur du matériel à $10 avec <10 Mo de RAM. Let's Go, PicoClaw !
+ ## ✨ Fonctionnalités -🪶 **Ultra-Léger** : Empreinte mémoire <10 Mo — 99% plus petit que les fonctionnalités essentielles d'OpenClaw.* +🪶 **Ultra-léger** : Empreinte mémoire du cœur <10 Mo — 99% plus petit qu'OpenClaw.* -💰 **Coût Minimal** : Suffisamment efficace pour fonctionner sur du matériel à $10 — 98% moins cher qu'un Mac mini. +💰 **Coût minimal** : Suffisamment efficace pour fonctionner sur du matériel à $10 — 98% moins cher qu'un Mac mini. -⚡️ **Démarrage Éclair** : Temps de démarrage 400X plus rapide, boot en <1 seconde même sur un cœur unique à 0,6 GHz. +⚡️ **Démarrage ultra-rapide** : 400x plus rapide au démarrage. Démarre en <1s même sur un processeur monocœur à 0,6 GHz. -🌍 **Véritable Portabilité** : Un seul binaire autonome pour RISC-V, ARM, MIPS et x86. Un clic et c'est parti ! +🌍 **Vraiment portable** : Binaire unique pour les architectures RISC-V, ARM, MIPS et x86. Un seul binaire, fonctionne partout ! -🤖 **Auto-Construit par l'IA** : Implémentation native en Go de manière autonome — 95% du cœur généré par l'Agent avec affinement humain dans la boucle. +🤖 **Auto-amorcé par IA** : Implémentation native pure Go — 95% du code principal a été généré par un Agent et affiné via une révision humaine en boucle. -🔌 **Support MCP** : Intégration native du [Model Context Protocol](https://modelcontextprotocol.io/) — connectez n'importe quel serveur MCP pour étendre les capacités de l'agent. +🔌 **Support MCP** : Intégration native du [Model Context Protocol](https://modelcontextprotocol.io/) — connectez n'importe quel serveur MCP pour étendre les capacités de l'Agent. -👁️ **Pipeline de Vision** : Envoyez des images et fichiers directement à l'agent — encodage base64 automatique pour les LLM multimodaux. +👁️ **Pipeline vision** : Envoyez des images et des fichiers directement à l'Agent — encodage base64 automatique pour les LLMs multimodaux. -🧠 **Routage Intelligent** : Routage de modèles basé sur des règles — les requêtes simples vont vers des modèles légers, économisant les coûts API. +🧠 **Routage intelligent** : Routage de modèles basé sur des règles — les requêtes simples vont vers des modèles légers, économisant les coûts API. -_*Les versions récentes peuvent utiliser 10–20 Mo en raison des fusions rapides de fonctionnalités. L'optimisation des ressources est prévue. La comparaison de démarrage est basée sur des benchmarks à cœur unique 0,8 GHz (voir tableau ci-dessous)._ +_*Les builds récents peuvent utiliser 10-20 Mo en raison des fusions rapides de PRs. L'optimisation des ressources est prévue. Comparaison de vitesse de démarrage basée sur des benchmarks monocœur à 0,8 GHz (voir tableau ci-dessous)._ + +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Langage** | TypeScript | Python | **Go** | -| **RAM** | >1 Go | >100 Mo | **< 10 Mo*** | -| **Démarrage**
(cœur 0,8 GHz) | >500s | >30s | **<1s** | -| **Coût** | Mac Mini $599 | La plupart des SBC Linux
~$50 | **N'importe quelle carte Linux**
**À partir de $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Langage** | TypeScript | Python | **Go** | +| **RAM** | >1 Go | >100 Mo | **< 10 Mo*** | +| **Temps de démarrage**
(cœur 0,8 GHz) | >500s | >30s | **<1s** | +| **Coût** | Mac Mini $599 | La plupart des cartes Linux ~$50 | **N'importe quelle carte Linux**
**à partir de $10** | PicoClaw -> 📋 **[Liste de Compatibilité Matérielle](docs/hardware-compatibility.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR ! +
+ +> **[Liste de compatibilité matérielle](docs/fr/hardware-compatibility.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR ! + +

+PicoClaw Hardware Compatibility +

## 🦾 Démonstration -### 🛠️ Flux de Travail Standard de l'Assistant +### 🛠️ Flux de travail standard de l'assistant - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 Ingénieur Full-Stack

🗂️ Gestion des Logs & Planification

🔎 Recherche Web & Apprentissage

Développer • Déployer • Mettre à l'échellePlanifier • Automatiser • MémoriserDécouvrir • Analyser • Tendances

Mode Ingénieur Full-Stack

Journalisation & Planification

Recherche Web & Apprentissage

Développer · Déployer · Mettre à l'échellePlanifier · Automatiser · MémoriserDécouvrir · Analyser · Tendances
-### 📱 Utiliser sur d'anciens téléphones Android - -Donnez une seconde vie à votre téléphone d'il y a dix ans ! Transformez-le en assistant IA intelligent avec PicoClaw. Démarrage rapide : - -1. **Installez [Termux](https://github.com/termux/termux-app)** (Téléchargez depuis [GitHub Releases](https://github.com/termux/termux-app/releases), ou recherchez sur F-Droid / Google Play). -2. **Exécutez les commandes** - -```bash -# Téléchargez la dernière version depuis https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot fournit une disposition standard du système de fichiers Linux -``` - -Puis suivez les instructions de la section « Démarrage Rapide » pour terminer la configuration ! - -PicoClaw - -### 🐜 Déploiement Innovant à Faible Empreinte +### 🐜 Déploiement innovant à faible empreinte PicoClaw peut être déployé sur pratiquement n'importe quel appareil Linux ! -- 9,9$ [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) version E (Ethernet) ou W (WiFi6), pour un Assistant Domotique Minimaliste -- 30~$50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou 100$ [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) pour la Maintenance Automatisée de Serveurs -- 50$ [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou 100$ [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) pour la Surveillance Intelligente +- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) édition E(Ethernet) ou W(WiFi6), pour un assistant domestique minimal +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), pour des opérations serveur automatisées +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), pour la surveillance intelligente -🌟 Encore plus de scénarios de déploiement vous attendent ! +🌟 D'autres cas de déploiement vous attendent ! + ## 📦 Installation ### Télécharger depuis picoclaw.io (Recommandé) -Visitez **[picoclaw.io](https://picoclaw.io)** — le site officiel détecte automatiquement votre plateforme et propose un téléchargement en un clic. Pas besoin de choisir manuellement une architecture. +Visitez **[picoclaw.io](https://picoclaw.io)** — le site officiel détecte automatiquement votre plateforme et fournit un téléchargement en un clic. Pas besoin de choisir manuellement une architecture. ### Télécharger le binaire précompilé @@ -178,80 +169,418 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Compiler, pas besoin d'installer +# Compiler le binaire principal make build +# Compiler le Web UI Launcher (requis pour le mode WebUI) +make build-launcher + # Compiler pour plusieurs plateformes make build-all -# Compiler pour Raspberry Pi Zero 2 W (32-bit : make build-linux-arm ; 64-bit : make build-linux-arm64) +# Compiler pour Raspberry Pi Zero 2 W (32 bits : make build-linux-arm ; 64 bits : make build-linux-arm64) make build-pi-zero -# Compiler et Installer +# Compiler et installer make install ``` -**Raspberry Pi Zero 2 W :** Utilisez le binaire correspondant à votre OS : Raspberry Pi OS 32-bit → `make build-linux-arm` ; 64-bit → `make build-linux-arm64`. Ou exécutez `make build-pi-zero` pour compiler les deux. +**Raspberry Pi Zero 2 W :** Utilisez le binaire correspondant à votre OS : Raspberry Pi OS 32 bits -> `make build-linux-arm` ; 64 bits -> `make build-linux-arm64`. Ou exécutez `make build-pi-zero` pour compiler les deux. -## 📚 Documentation +## 🚀 Guide de démarrage rapide -Pour des guides détaillés, consultez la documentation ci-dessous. Ce README ne couvre que le démarrage rapide. +### 🌐 WebUI Launcher (Recommandé pour le bureau) -| Sujet | Description | -|-------|-------------| -| 🐳 [Docker & Démarrage Rapide](docs/fr/docker.md) | Configuration Docker Compose, modes Launcher/Agent, configuration rapide | -| 💬 [Applications de Chat](docs/fr/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, et plus | -| ⚙️ [Configuration](docs/fr/configuration.md) | Variables d'environnement, structure du workspace, sources de compétences, bac à sable de sécurité, heartbeat | -| 🔌 [Fournisseurs & Modèles](docs/fr/providers.md) | 20+ fournisseurs LLM, routage de modèles, configuration model_list, architecture des fournisseurs | -| 🔄 [Spawn & Tâches Asynchrones](docs/fr/spawn-tasks.md) | Tâches rapides, tâches longues avec spawn, orchestration asynchrone de sous-agents | -| 🐛 [Dépannage](docs/fr/troubleshooting.md) | Problèmes courants et solutions | -| 🔧 [Configuration des Outils](docs/fr/tools_configuration.md) | Activation/désactivation par outil, politiques exec | -| 📋 [Compatibilité Matérielle](docs/hardware-compatibility.md) | Cartes testées, exigences minimales, comment ajouter votre carte | +Le WebUI Launcher fournit une interface basée sur navigateur pour la configuration et le chat. C'est la façon la plus simple de démarrer — aucune connaissance de la ligne de commande requise. -## ClawdChat Rejoignez le Réseau Social d'Agents +**Option 1 : Double-clic (Bureau)** -Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée. +Après téléchargement depuis [picoclaw.io](https://picoclaw.io), double-cliquez sur `picoclaw-launcher` (ou `picoclaw-launcher.exe` sous Windows). Votre navigateur s'ouvrira automatiquement sur `http://localhost:18800`. + +**Option 2 : Ligne de commande** + +```bash +picoclaw-launcher +# Ouvrez http://localhost:18800 dans votre navigateur +``` + +> [!TIP] +> **Accès distant / Docker / VM :** Ajoutez le flag `-public` pour écouter sur toutes les interfaces : +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**Pour commencer :** + +Ouvrez le WebUI, puis : **1)** Configurez un Provider (ajoutez votre clé API LLM) -> **2)** Configurez un Channel (ex. Telegram) -> **3)** Démarrez le Gateway -> **4)** Chattez ! + +Pour la documentation détaillée du WebUI, voir [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (alternative) + +```bash +# 1. Cloner ce dépôt +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête +# (se déclenche uniquement quand config.json et workspace/ sont tous deux absents) +docker compose -f docker/docker-compose.yml --profile launcher up +# Le conteneur affiche "First-run setup complete." et s'arrête. + +# 3. Définir vos clés API +vim docker/data/config.json + +# 4. Démarrer +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Ouvrez http://localhost:18800 +``` + +> **Utilisateurs Docker / VM :** Le Gateway écoute sur `127.0.0.1` par défaut. Définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` ou utilisez le flag `-public` pour le rendre accessible depuis l'hôte. + +```bash +# Vérifier les logs +docker compose -f docker/docker-compose.yml logs -f + +# Arrêter +docker compose -f docker/docker-compose.yml --profile launcher down + +# Mettre à jour +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher (Recommandé pour les environnements sans interface / SSH) + +Le TUI (Terminal UI) Launcher fournit une interface terminal complète pour la configuration et la gestion. Idéal pour les serveurs, Raspberry Pi et autres environnements sans interface graphique. + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**Pour commencer :** + +Utilisez les menus TUI pour : **1)** Configurer un Provider -> **2)** Configurer un Channel -> **3)** Démarrer le Gateway -> **4)** Chattez ! + +Pour la documentation détaillée du TUI, voir [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Donnez une seconde vie à votre téléphone vieux de dix ans ! Transformez-le en assistant IA intelligent avec PicoClaw. + +**Option 1 : Termux (disponible maintenant)** + +1. Installez [Termux](https://github.com/termux/termux-app) (téléchargez depuis [GitHub Releases](https://github.com/termux/termux-app/releases), ou cherchez dans F-Droid / Google Play) +2. Exécutez les commandes suivantes : + +```bash +# Télécharger la dernière version +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot fournit une arborescence Linux standard +``` + +Suivez ensuite la section Terminal Launcher ci-dessous pour terminer la configuration. + +PicoClaw on Termux + +**Option 2 : Installation APK (bientôt disponible)** + +Un APK Android autonome avec WebUI intégré est en développement. Restez à l'écoute ! + +
+Terminal Launcher (pour les environnements à ressources limitées) + +Pour les environnements minimaux où seul le binaire principal `picoclaw` est disponible (sans Launcher UI), vous pouvez tout configurer via la ligne de commande et un fichier de configuration JSON. + +**1. Initialiser** + +```bash +picoclaw onboard +``` + +Cela crée `~/.picoclaw/config.json` et le répertoire workspace. + +**2. Configurer** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> Voir `config/config.example.json` dans le dépôt pour un modèle de configuration complet avec toutes les options disponibles. + +**3. Chatter** + +```bash +# Question ponctuelle +picoclaw agent -m "What is 2+2?" + +# Mode interactif +picoclaw agent + +# Démarrer le gateway pour l'intégration d'applications de chat +picoclaw gateway +``` + +
+ + +## 🔌 Providers (LLM) + +PicoClaw supporte plus de 30 providers LLM via la configuration `model_list`. Utilisez le format `protocole/modèle` : + +| Provider | Protocole | Clé API | Notes | +|----------|-----------|---------|-------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Requise | GPT-5.4, GPT-4o, o3, etc. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Requise | Claude Opus 4.6, Sonnet 4.6, etc. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Requise | Gemini 3 Flash, 2.5 Pro, etc. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Requise | 200+ modèles, API unifiée | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Requise | GLM-4.7, GLM-5, etc. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Requise | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Requise | Modèles Doubao, Ark | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Requise | Qwen3, Qwen-Max, etc. | +| [Groq](https://console.groq.com/keys) | `groq/` | Requise | Inférence rapide (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Requise | Modèles Kimi | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Requise | Modèles MiniMax | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Requise | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Requise | Modèles hébergés NVIDIA | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Requise | Inférence rapide | +| [Novita AI](https://novita.ai/) | `novita/` | Requise | Divers modèles open | +| [Ollama](https://ollama.com/) | `ollama/` | Non requise | Modèles locaux, auto-hébergé | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Non requise | Déploiement local, compatible OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Variable | Proxy pour 100+ providers | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Requise | Déploiement Azure entreprise | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Connexion par code appareil | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+Déploiement local (Ollama, vLLM, etc.) + +**Ollama :** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM :** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Pour les détails complets de configuration des providers, voir [Providers & Models](docs/fr/providers.md). + +
+ +## 💬 Channels (Applications de chat) + +Parlez à votre PicoClaw via plus de 17 plateformes de messagerie : + +| Channel | Configuration | Protocole | Docs | +|---------|---------------|-----------|------| +| **Telegram** | Facile (token bot) | Long polling | [Guide](docs/channels/telegram/README.fr.md) | +| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](docs/channels/discord/README.fr.md) | +| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](docs/fr/chat-apps.md#whatsapp) | +| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](docs/fr/chat-apps.md#weixin) | +| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.fr.md) | +| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](docs/channels/slack/README.fr.md) | +| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.fr.md) | +| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](docs/channels/dingtalk/README.fr.md) | +| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.fr.md) | +| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](docs/channels/line/README.fr.md) | +| **WeCom Bot** | Moyen (URL webhook) | Webhook | [Guide](docs/channels/wecom/wecom_bot/README.fr.md) | +| **WeCom App** | Moyen (identifiants corp) | Webhook | [Guide](docs/channels/wecom/wecom_app/README.fr.md) | +| **WeCom AI Bot** | Moyen (token + clé AES) | WebSocket / Webhook | [Guide](docs/channels/wecom/wecom_aibot/README.fr.md) | +| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](docs/fr/chat-apps.md#irc) | +| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](docs/channels/onebot/README.fr.md) | +| **MaixCam** | Facile (activer) | Socket TCP | [Guide](docs/channels/maixcam/README.fr.md) | +| **Pico** | Facile (activer) | Protocole natif | Intégré | +| **Pico Client** | Facile (URL WebSocket) | WebSocket | Intégré | + +> Tous les channels basés sur webhook partagent un seul serveur HTTP Gateway (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP partagé. + +Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](docs/fr/chat-apps.md). + +## 🔧 Outils + +### 🔍 Recherche Web + +PicoClaw peut effectuer des recherches sur le web pour fournir des informations à jour. Configurez dans `tools.web` : + +| Moteur de recherche | Clé API | Niveau gratuit | Lien | +|--------------------|---------|----------------|------| +| DuckDuckGo | Non requise | Illimité | Fallback intégré | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Requise | 1000 requêtes/jour | IA, optimisé pour le chinois | +| [Tavily](https://tavily.com) | Requise | 1000 requêtes/mois | Optimisé pour les Agents IA | +| [Brave Search](https://brave.com/search/api) | Requise | 2000 requêtes/mois | Rapide et privé | +| [Perplexity](https://www.perplexity.ai) | Requise | Payant | Recherche propulsée par IA | +| [SearXNG](https://github.com/searxng/searxng) | Non requise | Auto-hébergé | Métamoteur de recherche gratuit | +| [GLM Search](https://open.bigmodel.cn/) | Requise | Variable | Recherche web Zhipu | + +### ⚙️ Autres outils + +PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](docs/fr/tools_configuration.md) pour les détails. + +## 🎯 Skills + +Les Skills sont des capacités modulaires qui étendent votre Agent. Elles sont chargées depuis les fichiers `SKILL.md` dans votre workspace. + +**Installer des Skills depuis ClawHub :** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Configurer le token ClawHub** (optionnel, pour des limites de débit plus élevées) : + +Ajoutez à votre `config.json` : +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Pour plus de détails, voir [Configuration des outils - Skills](docs/fr/tools_configuration.md#skills-tool). + +## 🔗 MCP (Model Context Protocol) + +PicoClaw supporte nativement [MCP](https://modelcontextprotocol.io/) — connectez n'importe quel serveur MCP pour étendre les capacités de votre Agent avec des outils et sources de données externes. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](docs/fr/tools_configuration.md#mcp-tool). + +## ClawdChat Rejoignez le réseau social des Agents + +Connectez PicoClaw au réseau social des Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée. **Lisez `https://clawdchat.ai/skill.md` et suivez les instructions pour rejoindre [ClawdChat.ai](https://clawdchat.ai)** ## 🖥️ Référence CLI -| Commande | Description | -| ------------------------- | ---------------------------------- | -| `picoclaw onboard` | Initialiser la config & le workspace | -| `picoclaw agent -m "..."` | Discuter avec l'agent | -| `picoclaw agent` | Mode chat interactif | -| `picoclaw gateway` | Démarrer le gateway | -| `picoclaw status` | Afficher le statut | -| `picoclaw version` | Afficher les infos de version | -| `picoclaw cron list` | Lister les tâches planifiées | -| `picoclaw cron add ...` | Ajouter une tâche planifiée | -| `picoclaw cron disable` | Désactiver une tâche planifiée | -| `picoclaw cron remove` | Supprimer une tâche planifiée | -| `picoclaw skills list` | Lister les compétences installées | -| `picoclaw skills install` | Installer une compétence | -| `picoclaw migrate` | Migrer les données des anciennes versions | -| `picoclaw auth login` | S'authentifier auprès des fournisseurs | -| `picoclaw model` | Voir ou changer le modèle par défaut | +| Commande | Description | +| ------------------------- | ---------------------------------------- | +| `picoclaw onboard` | Initialiser la config & le workspace | +| `picoclaw onboard weixin` | Connecter un compte WeChat via QR | +| `picoclaw agent -m "..."` | Chatter avec l'agent | +| `picoclaw agent` | Mode chat interactif | +| `picoclaw gateway` | Démarrer le gateway | +| `picoclaw status` | Afficher le statut | +| `picoclaw version` | Afficher les informations de version | +| `picoclaw model` | Voir ou changer le modèle par défaut | +| `picoclaw cron list` | Lister toutes les tâches planifiées | +| `picoclaw cron add ...` | Ajouter une tâche planifiée | +| `picoclaw cron disable` | Désactiver une tâche planifiée | +| `picoclaw cron remove` | Supprimer une tâche planifiée | +| `picoclaw skills list` | Lister les Skills installées | +| `picoclaw skills install` | Installer une Skill | +| `picoclaw migrate` | Migrer les données depuis d'anciennes versions | +| `picoclaw auth login` | S'authentifier auprès des providers | + +### ⏰ Tâches planifiées / Rappels + +PicoClaw supporte les rappels planifiés et les tâches récurrentes via l'outil `cron` : + +* **Rappels ponctuels** : "Rappelle-moi dans 10 minutes" -> se déclenche une fois après 10 min +* **Tâches récurrentes** : "Rappelle-moi toutes les 2 heures" -> se déclenche toutes les 2 heures +* **Expressions cron** : "Rappelle-moi à 9h chaque jour" -> utilise une expression cron -### Tâches Planifiées / Rappels +## 📚 Documentation -PicoClaw prend en charge les rappels planifiés et les tâches récurrentes via l'outil `cron` : +Pour des guides détaillés au-delà de ce README : -* **Rappels ponctuels** : « Rappelle-moi dans 10 minutes » → se déclenche une fois après 10 min -* **Tâches récurrentes** : « Rappelle-moi toutes les 2 heures » → se déclenche toutes les 2 heures -* **Expressions cron** : « Rappelle-moi à 9h chaque jour » → utilise une expression cron +| Sujet | Description | +|-------|-------------| +| [Docker & Démarrage rapide](docs/fr/docker.md) | Configuration Docker Compose, modes Launcher/Agent | +| [Applications de chat](docs/fr/chat-apps.md) | Guides de configuration pour les 17+ channels | +| [Configuration](docs/fr/configuration.md) | Variables d'environnement, structure du workspace, sandbox de sécurité | +| [Providers & Modèles](docs/fr/providers.md) | 30+ providers LLM, routage de modèles, configuration model_list | +| [Spawn & Tâches asynchrones](docs/fr/spawn-tasks.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones | +| [Hooks](docs/hooks/README.md) | Système de hooks événementiels : observateurs, intercepteurs, hooks d'approbation | +| [Steering](docs/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution | +| [SubTurn](docs/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie | +| [Dépannage](docs/fr/troubleshooting.md) | Problèmes courants et solutions | +| [Configuration des outils](docs/fr/tools_configuration.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills | +| [Compatibilité matérielle](docs/fr/hardware-compatibility.md) | Cartes testées, exigences minimales | -## 🤝 Contribuer & Feuille de Route +## 🤝 Contribuer & Roadmap -Les PR sont les bienvenues ! Le code est intentionnellement petit et lisible. 🤗 +Les PRs sont les bienvenues ! Le code source est intentionnellement petit et lisible. -Consultez notre [Feuille de Route Communautaire](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) complète. +Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives. -Groupe de développeurs en construction, rejoignez-nous après votre première PR fusionnée ! +Groupe de développeurs en construction, rejoignez-le après votre première PR fusionnée ! Groupes d'utilisateurs : -discord : +Discord : + +WeChat : +WeChat group QR code + + + -PicoClaw diff --git a/README.id.md b/README.id.md index 644f8cb0a1..6b7025ffdd 100644 --- a/README.id.md +++ b/README.id.md @@ -1,9 +1,9 @@
- PicoClaw +PicoClaw -

PicoClaw: Asisten AI Super Ringan berbasis Go

+

PicoClaw: Asisten AI Super Ringan berbasis Go

-

Perangkat Keras $10 · RAM <10MB · Boot <1 Detik · Ayo, Berangkat!

+

Perangkat Keras $10 · RAM 10MB · Boot ms · Let's Go, PicoClaw!

Go Hardware @@ -24,135 +24,125 @@ --- -> **PicoClaw** adalah proyek open-source independen yang diinisiasi oleh [Sipeed](https://sipeed.com). Ditulis sepenuhnya dalam **Go** — bukan fork dari OpenClaw, NanoBot, atau proyek lainnya. +> **PicoClaw** adalah proyek open-source independen yang diinisiasi oleh [Sipeed](https://sipeed.com), ditulis sepenuhnya dalam **Go** — bukan fork dari OpenClaw, NanoBot, atau proyek lainnya. -🦐 PicoClaw adalah asisten AI pribadi yang super ringan, terinspirasi dari [NanoBot](https://github.com/HKUDS/nanobot), ditulis ulang sepenuhnya dalam Go melalui proses "self-bootstrapping" — di mana AI Agent itu sendiri yang memandu seluruh migrasi arsitektur dan optimasi kode. +**PicoClaw** adalah asisten AI pribadi yang super ringan, terinspirasi dari [NanoBot](https://github.com/HKUDS/nanobot). Dibangun ulang dari awal dalam **Go** melalui proses "self-bootstrapping" — AI Agent itu sendiri yang memandu migrasi arsitektur dan optimasi kode. -⚡️ Berjalan di perangkat keras $10 dengan RAM <10MB: Hemat 99% memori dibanding OpenClaw dan 98% lebih murah dibanding Mac mini! +**Berjalan di perangkat keras $10 dengan RAM <10MB** — hemat 99% memori dibanding OpenClaw dan 98% lebih murah dari Mac mini! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 KEAMANAN & SALURAN RESMI** -> -> * **TANPA KRIPTO:** PicoClaw **TIDAK** memiliki token/koin resmi. Semua klaim di `pump.fun` atau platform trading lainnya adalah **PENIPUAN**. +> **Peringatan Keamanan** > +> * **TANPA KRIPTO:** PicoClaw **tidak** menerbitkan token atau cryptocurrency resmi apa pun. Semua klaim di `pump.fun` atau platform trading lainnya adalah **penipuan**. > * **DOMAIN RESMI:** Satu-satunya website resmi adalah **[picoclaw.io](https://picoclaw.io)**, dan website perusahaan adalah **[sipeed.com](https://sipeed.com)** -> * **Peringatan:** Banyak domain `.ai/.org/.com/.net/...` yang didaftarkan oleh pihak ketiga. -> * **Peringatan:** PicoClaw masih dalam tahap pengembangan awal dan mungkin memiliki masalah keamanan jaringan yang belum teratasi. Jangan deploy ke lingkungan produksi sebelum rilis v1.0. -> * **Catatan:** PicoClaw baru-baru ini menggabungkan banyak PR, yang mungkin mengakibatkan penggunaan memori lebih besar (10–20MB) pada versi terbaru. Kami berencana untuk memprioritaskan optimasi sumber daya segera setelah fitur saat ini mencapai kondisi stabil. +> * **WASPADA:** Banyak domain `.ai/.org/.com/.net/...` telah didaftarkan oleh pihak ketiga. Jangan percaya mereka. +> * **CATATAN:** PicoClaw masih dalam tahap pengembangan awal yang cepat. Mungkin ada masalah keamanan yang belum terselesaikan. Jangan deploy ke produksi sebelum v1.0. +> * **CATATAN:** PicoClaw baru-baru ini menggabungkan banyak PR. Build terbaru mungkin menggunakan RAM 10-20MB. Optimasi sumber daya direncanakan setelah fitur stabil. ## 📢 Berita -2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental gateway hot-reload, gerbang keamanan cron, dan 2 perbaikan keamanan. PicoClaw kini di **25K ⭐**! +2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental Gateway hot-reload, gerbang keamanan Cron, dan 2 perbaikan keamanan. PicoClaw telah mencapai **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Update terbesar!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, dan routing model. +2026-03-09 🎉 **v0.2.1 — Update terbesar sejauh ini!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, routing model. -2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan launcher Web UI. +2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan Web UI Launcher. -2026-02-26 🎉 PicoClaw mencapai **20K bintang** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas diluncurkan. +2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif.

-Berita lama... +Berita sebelumnya... -2026-02-16 🎉 PicoClaw mencapai 12K bintang dalam satu minggu! Peran maintainer komunitas dan [roadmap](ROADMAP.md) resmi diposting. +2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](ROADMAP.md) resmi diluncurkan. -2026-02-13 🎉 PicoClaw mencapai 5000 bintang dalam 4 hari! Roadmap Proyek dan pengaturan Grup Pengembang sedang berjalan. +2026-02-13 🎉 PicoClaw menembus 5000 Stars dalam 4 hari! Roadmap proyek dan grup pengembang sedang dalam proses. -2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. 🦐 PicoClaw, Ayo Berangkat! +2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. Let's Go, PicoClaw!
## ✨ Fitur -🪶 **Super Ringan**: Penggunaan memori <10MB — 99% lebih kecil dari fungsionalitas inti OpenClaw.* +🪶 **Super Ringan**: Penggunaan memori inti <10MB — 99% lebih kecil dari OpenClaw.* 💰 **Biaya Minimal**: Cukup efisien untuk berjalan di perangkat keras $10 — 98% lebih murah dari Mac mini. -⚡️ **Secepat Kilat**: Waktu startup 400X lebih cepat, boot dalam <1 detik bahkan di prosesor single core 0,6GHz. +⚡️ **Boot Secepat Kilat**: Startup 400x lebih cepat. Boot dalam <1 detik bahkan di prosesor single-core 0,6GHz. -🌍 **Portabilitas Sejati**: Satu binary mandiri untuk RISC-V, ARM, MIPS, dan x86, Satu Klik Langsung Jalan! +🌍 **Portabilitas Sejati**: Satu binary untuk RISC-V, ARM, MIPS, dan x86. Satu binary, jalan di mana saja! -🤖 **AI-Bootstrapped**: Implementasi Go-native secara otonom — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop. +🤖 **AI-Bootstrapped**: Implementasi Go native murni — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop. -🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas agent. +🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent. -👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke agent — encoding base64 otomatis untuk LLM multimodal. +👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke Agent — encoding base64 otomatis untuk LLM multimodal. 🧠 **Routing Cerdas**: Routing model berbasis aturan — kueri sederhana diarahkan ke model ringan, menghemat biaya API. -_*Versi terbaru mungkin menggunakan 10–20MB karena penggabungan fitur yang cepat. Optimasi sumber daya direncanakan. Perbandingan startup berdasarkan benchmark prosesor single-core 0,8GHz (lihat tabel di bawah)._ +_*Build terbaru mungkin menggunakan 10-20MB karena penggabungan PR yang cepat. Optimasi sumber daya direncanakan. Perbandingan kecepatan boot berdasarkan benchmark single-core 0,8GHz (lihat tabel di bawah)._ + +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Bahasa** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **Startup**
(0,8GHz core) | >500d | >30d | **<1d** | -| **Biaya** | Mac Mini $599 | Kebanyakan Linux SBC
~$50 | **Semua Board Linux**
**Mulai dari $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Bahasa** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Waktu Boot**
(core 0,8GHz) | >500d | >30d | **<1d** | +| **Biaya** | Mac Mini $599 | Kebanyakan board Linux ~$50 | **Board Linux mana pun**
**mulai $10** | PicoClaw +
+ +> **[Daftar Kompatibilitas Hardware](docs/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR! + +

+PicoClaw Hardware Compatibility +

+ ## 🦾 Demonstrasi ### 🛠️ Alur Kerja Asisten Standar - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 Full-Stack Engineer

🗂️ Pencatatan & Manajemen Perencanaan

🔎 Pencarian Web & Pembelajaran

Develop • Deploy • ScaleJadwal • Otomasi • MemoriPenemuan • Wawasan • Tren

Mode Full-Stack Engineer

Pencatatan & Perencanaan

Pencarian Web & Pembelajaran

Develop · Deploy · ScaleJadwal · Otomasi · IngatTemukan · Wawasan · Tren
-### 📱 Jalankan di HP Android Lama - -Berikan kehidupan kedua untuk HP lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw. Panduan Cepat: - -1. **Instal [Termux](https://github.com/termux/termux-app)** (Unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play). -2. **Jalankan perintah** - -```bash -# Unduh rilis terbaru dari https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard -``` - -Kemudian ikuti instruksi di bagian "Panduan Cepat" untuk menyelesaikan konfigurasi! - -PicoClaw - ### 🐜 Deploy Inovatif dengan Footprint Rendah PicoClaw dapat di-deploy di hampir semua perangkat Linux! -- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk Home Assistant Minimal -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) untuk Pemeliharaan Server Otomatis -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) untuk Pemantauan Cerdas +- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk home assistant minimal +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), untuk operasi server otomatis +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), untuk pengawasan cerdas @@ -160,11 +150,15 @@ PicoClaw dapat di-deploy di hampir semua perangkat Linux! ## 📦 Instalasi -### Instal dengan binary yang sudah dikompilasi +### Unduh dari picoclaw.io (Direkomendasikan) + +Kunjungi **[picoclaw.io](https://picoclaw.io)** — website resmi mendeteksi platform Anda secara otomatis dan menyediakan unduhan satu klik. Tidak perlu memilih arsitektur secara manual. -Unduh binary untuk platform Anda dari halaman [Releases](https://github.com/sipeed/picoclaw/releases). +### Unduh binary yang sudah dikompilasi -### Instal dari source (fitur terbaru, disarankan untuk pengembangan) +Atau, unduh binary untuk platform Anda dari halaman [GitHub Releases](https://github.com/sipeed/picoclaw/releases). + +### Build dari source (untuk pengembangan) ```bash git clone https://github.com/sipeed/picoclaw.git @@ -172,79 +166,414 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Build, tidak perlu instal +# Build binary inti make build +# Build Web UI Launcher (diperlukan untuk mode WebUI) +make build-launcher + # Build untuk berbagai platform make build-all # Build untuk Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) make build-pi-zero -# Build dan Instal +# Build dan instal make install ``` -**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya. +**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya. -## 📚 Dokumentasi +## 🚀 Panduan Memulai Cepat -Untuk panduan lengkap, lihat dokumen di bawah. README ini hanya berisi panduan cepat. +### 🌐 WebUI Launcher (Direkomendasikan untuk Desktop) -| Topik | Deskripsi | -|-------|-----------| -| 🐳 [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent, konfigurasi Panduan Cepat | -| 💬 [Aplikasi Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom, dan lainnya | -| ⚙️ [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sumber skill, sandbox keamanan, heartbeat | -| 🔌 [Provider & Model](docs/providers.md) | 20+ provider LLM, routing model, konfigurasi model_list, arsitektur provider | -| 🔄 [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async | -| 🐛 [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya | -| 🔧 [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan tool, kebijakan exec | +WebUI Launcher menyediakan antarmuka berbasis browser untuk konfigurasi dan chat. Ini adalah cara termudah untuk memulai — tidak perlu pengetahuan command-line. + +**Opsi 1: Klik dua kali (Desktop)** + +Setelah mengunduh dari [picoclaw.io](https://picoclaw.io), klik dua kali `picoclaw-launcher` (atau `picoclaw-launcher.exe` di Windows). Browser Anda akan terbuka otomatis di `http://localhost:18800`. + +**Opsi 2: Command line** + +```bash +picoclaw-launcher +# Buka http://localhost:18800 di browser Anda +``` + +> [!TIP] +> **Akses jarak jauh / Docker / VM:** Tambahkan flag `-public` untuk mendengarkan di semua antarmuka: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**Memulai:** + +Buka WebUI, lalu: **1)** Konfigurasi Provider (tambahkan API key LLM Anda) -> **2)** Konfigurasi Channel (mis. Telegram) -> **3)** Mulai Gateway -> **4)** Chat! + +Untuk dokumentasi WebUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (alternatif) + +```bash +# 1. Clone repo ini +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Jalankan pertama kali — otomatis membuat docker/data/config.json lalu keluar +# (hanya terpicu ketika config.json dan workspace/ keduanya tidak ada) +docker compose -f docker/docker-compose.yml --profile launcher up +# Container mencetak "First-run setup complete." dan berhenti. + +# 3. Atur API key Anda +vim docker/data/config.json + +# 4. Mulai +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Buka http://localhost:18800 +``` + +> **Pengguna Docker / VM:** Gateway mendengarkan di `127.0.0.1` secara default. Atur `PICOCLAW_GATEWAY_HOST=0.0.0.0` atau gunakan flag `-public` agar dapat diakses dari host. + +```bash +# Cek log +docker compose -f docker/docker-compose.yml logs -f + +# Hentikan +docker compose -f docker/docker-compose.yml --profile launcher down + +# Update +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher (Direkomendasikan untuk Headless / SSH) + +TUI (Terminal UI) Launcher menyediakan antarmuka terminal lengkap untuk konfigurasi dan manajemen. Ideal untuk server, Raspberry Pi, dan lingkungan headless lainnya. + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**Memulai:** + +Gunakan menu TUI untuk: **1)** Konfigurasi Provider -> **2)** Konfigurasi Channel -> **3)** Mulai Gateway -> **4)** Chat! + +Untuk dokumentasi TUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Berikan kehidupan kedua untuk ponsel lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw. + +**Opsi 1: Termux (tersedia sekarang)** + +1. Instal [Termux](https://github.com/termux/termux-app) (unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play) +2. Jalankan perintah berikut: + +```bash +# Unduh rilis terbaru +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot menyediakan tata letak filesystem Linux standar +``` + +Kemudian ikuti bagian Terminal Launcher di bawah untuk menyelesaikan konfigurasi. + +PicoClaw on Termux + +**Opsi 2: Instal APK (segera hadir)** + +APK Android mandiri dengan WebUI bawaan sedang dalam pengembangan. Pantau terus! + +
+Terminal Launcher (untuk lingkungan dengan sumber daya terbatas) + +Untuk lingkungan minimal di mana hanya binary inti `picoclaw` yang tersedia (tanpa Launcher UI), Anda dapat mengonfigurasi semuanya melalui command line dan file konfigurasi JSON. + +**1. Inisialisasi** + +```bash +picoclaw onboard +``` + +Ini membuat `~/.picoclaw/config.json` dan direktori workspace. + +**2. Konfigurasi** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> Lihat `config/config.example.json` di repo untuk template konfigurasi lengkap dengan semua opsi yang tersedia. + +**3. Chat** + +```bash +# Pertanyaan satu kali +picoclaw agent -m "What is 2+2?" + +# Mode interaktif +picoclaw agent + +# Mulai gateway untuk integrasi aplikasi chat +picoclaw gateway +``` + +
+ +## 🔌 Providers (LLM) + +PicoClaw mendukung 30+ provider LLM melalui konfigurasi `model_list`. Gunakan format `protocol/model`: + +| Provider | Protocol | API Key | Catatan | +|----------|----------|---------|---------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Diperlukan | GPT-5.4, GPT-4o, o3, dll. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Diperlukan | Claude Opus 4.6, Sonnet 4.6, dll. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Diperlukan | Gemini 3 Flash, 2.5 Pro, dll. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Diperlukan | 200+ model, API terpadu | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Diperlukan | GLM-4.7, GLM-5, dll. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Diperlukan | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Diperlukan | Doubao, model Ark | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Diperlukan | Qwen3, Qwen-Max, dll. | +| [Groq](https://console.groq.com/keys) | `groq/` | Diperlukan | Inferensi cepat (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Diperlukan | Model Kimi | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Diperlukan | Model MiniMax | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Diperlukan | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Diperlukan | Model yang di-host NVIDIA | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Diperlukan | Inferensi cepat | +| [Novita AI](https://novita.ai/) | `novita/` | Diperlukan | Berbagai model open | +| [Ollama](https://ollama.com/) | `ollama/` | Tidak perlu | Model lokal, self-hosted | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Tidak perlu | Deploy lokal, kompatibel OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Bervariasi | Proxy untuk 100+ provider | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Diperlukan | Deploy Azure enterprise | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login dengan device code | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+Deploy lokal (Ollama, vLLM, dll.) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](docs/providers.md). + +
+ +## 💬 Channels (Aplikasi Chat) + +Bicara dengan PicoClaw Anda melalui 17+ platform pesan: + +| Channel | Pengaturan | Protocol | Dokumentasi | +|---------|------------|----------|-------------| +| **Telegram** | Mudah (bot token) | Long polling | [Panduan](docs/channels/telegram/README.md) | +| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) | +| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](docs/chat-apps.md#whatsapp) | +| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](docs/chat-apps.md#weixin) | +| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) | +| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](docs/channels/slack/README.md) | +| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) | +| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](docs/channels/dingtalk/README.md) | +| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) | +| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](docs/channels/line/README.md) | +| **WeCom Bot** | Sedang (webhook URL) | Webhook | [Panduan](docs/channels/wecom/wecom_bot/README.md) | +| **WeCom App** | Sedang (corp credentials) | Webhook | [Panduan](docs/channels/wecom/wecom_app/README.md) | +| **WeCom AI Bot** | Sedang (token + AES key) | WebSocket / Webhook | [Panduan](docs/channels/wecom/wecom_aibot/README.md) | +| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](docs/chat-apps.md#irc) | +| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) | +| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) | +| **Pico** | Mudah (aktifkan) | Native protocol | Bawaan | +| **Pico Client** | Mudah (WebSocket URL) | WebSocket | Bawaan | + +> Semua channel berbasis webhook berbagi satu server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu menggunakan mode WebSocket/SDK dan tidak menggunakan server HTTP bersama. + +Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](docs/chat-apps.md). + +## 🔧 Tools + +### 🔍 Pencarian Web + +PicoClaw dapat mencari web untuk memberikan informasi terkini. Konfigurasi di `tools.web`: + +| Mesin Pencari | API Key | Tier Gratis | Tautan | +|--------------|---------|-------------|--------| +| DuckDuckGo | Tidak perlu | Tidak terbatas | Fallback bawaan | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Diperlukan | 1000 kueri/hari | Bertenaga AI, dioptimalkan untuk bahasa Mandarin | +| [Tavily](https://tavily.com) | Diperlukan | 1000 kueri/bulan | Dioptimalkan untuk AI Agent | +| [Brave Search](https://brave.com/search/api) | Diperlukan | 2000 kueri/bulan | Cepat dan privat | +| [Perplexity](https://www.perplexity.ai) | Diperlukan | Berbayar | Pencarian bertenaga AI | +| [SearXNG](https://github.com/searxng/searxng) | Tidak perlu | Self-hosted | Mesin metasearch gratis | +| [GLM Search](https://open.bigmodel.cn/) | Diperlukan | Bervariasi | Pencarian web Zhipu | + +### ⚙️ Tools Lainnya + +PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](docs/tools_configuration.md) untuk detail. + +## 🎯 Skills + +Skills adalah kapabilitas modular yang memperluas Agent Anda. Dimuat dari file `SKILL.md` di workspace Anda. + +**Instal skills dari ClawHub:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Konfigurasi token ClawHub** (opsional, untuk rate limit lebih tinggi): + +Tambahkan ke `config.json` Anda: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](docs/tools_configuration.md#skills-tool). + +## 🔗 MCP (Model Context Protocol) + +PicoClaw mendukung [MCP](https://modelcontextprotocol.io/) secara native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent Anda dengan tools dan sumber data eksternal. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](docs/tools_configuration.md#mcp-tool). ## ClawdChat Bergabung dengan Jaringan Sosial Agent -Hubungkan Picoclaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi. +Hubungkan PicoClaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi mana pun. **Baca `https://clawdchat.ai/skill.md` dan ikuti instruksi untuk bergabung dengan [ClawdChat.ai](https://clawdchat.ai)** ## 🖥️ Referensi CLI -| Perintah | Deskripsi | -| ------------------------- | -------------------------------- | -| `picoclaw onboard` | Inisialisasi konfigurasi & workspace | +| Perintah | Deskripsi | +| -------------------------- | -------------------------------- | +| `picoclaw onboard` | Inisialisasi konfigurasi & workspace | +| `picoclaw onboard weixin` | Hubungkan akun WeChat via QR | | `picoclaw agent -m "..."` | Chat dengan agent | -| `picoclaw agent` | Mode chat interaktif | -| `picoclaw gateway` | Mulai gateway | -| `picoclaw status` | Tampilkan status | -| `picoclaw version` | Tampilkan info versi | -| `picoclaw model` | Lihat atau ubah model default | -| `picoclaw cron list` | Daftar semua tugas terjadwal | -| `picoclaw cron add ...` | Tambah tugas terjadwal | -| `picoclaw cron disable` | Nonaktifkan tugas terjadwal | -| `picoclaw cron remove` | Hapus tugas terjadwal | -| `picoclaw skills list` | Daftar skill yang terinstal | -| `picoclaw skills install` | Instal skill | -| `picoclaw migrate` | Migrasi data dari versi lama | -| `picoclaw auth login` | Autentikasi dengan provider | - -### Tugas Terjadwal / Pengingat +| `picoclaw agent` | Mode chat interaktif | +| `picoclaw gateway` | Mulai gateway | +| `picoclaw status` | Tampilkan status | +| `picoclaw version` | Tampilkan info versi | +| `picoclaw model` | Lihat atau ganti model default | +| `picoclaw cron list` | Daftar semua tugas terjadwal | +| `picoclaw cron add ...` | Tambah tugas terjadwal | +| `picoclaw cron disable` | Nonaktifkan tugas terjadwal | +| `picoclaw cron remove` | Hapus tugas terjadwal | +| `picoclaw skills list` | Daftar skill yang terinstal | +| `picoclaw skills install` | Instal skill | +| `picoclaw migrate` | Migrasi data dari versi lama | +| `picoclaw auth login` | Autentikasi dengan provider | + +### ⏰ Tugas Terjadwal / Pengingat PicoClaw mendukung pengingat terjadwal dan tugas berulang melalui tool `cron`: -* **Pengingat satu kali**: "Ingatkan saya dalam 10 menit" → terpicu sekali setelah 10 menit -* **Tugas berulang**: "Ingatkan saya setiap 2 jam" → terpicu setiap 2 jam -* **Ekspresi cron**: "Ingatkan saya jam 9 pagi setiap hari" → menggunakan ekspresi cron +* **Pengingat satu kali**: "Ingatkan saya dalam 10 menit" -> terpicu sekali setelah 10 menit +* **Tugas berulang**: "Ingatkan saya setiap 2 jam" -> terpicu setiap 2 jam +* **Ekspresi cron**: "Ingatkan saya jam 9 pagi setiap hari" -> menggunakan ekspresi cron + +## 📚 Dokumentasi + +Untuk panduan lengkap di luar README ini: + +| Topik | Deskripsi | +|-------|-----------| +| [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent | +| [Aplikasi Chat](docs/chat-apps.md) | Semua 17+ panduan pengaturan channel | +| [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan | +| [Providers & Models](docs/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list | +| [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async | +| [Hooks](docs/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook | +| [Steering](docs/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan | +| [SubTurn](docs/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup | +| [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya | +| [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills | +| [Kompatibilitas Hardware](docs/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum | ## 🤝 Kontribusi & Roadmap -PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca. 🤗 +PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca. -Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) lengkap kami. +Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan. Grup pengembang sedang dibangun, bergabunglah setelah PR pertama Anda di-merge! Grup Pengguna: -discord: +Discord: + +WeChat: +Kode QR grup WeChat -PicoClaw diff --git a/README.it.md b/README.it.md index bb460e8ce6..dae541a17c 100644 --- a/README.it.md +++ b/README.it.md @@ -1,9 +1,9 @@
- PicoClaw +PicoClaw -

PicoClaw: Assistente IA Ultra-Efficiente in Go

+

PicoClaw: Assistente IA Ultra-Efficiente in Go

-

Hardware da $10 · <10MB RAM · Boot in <1s · 皮皮虾,我们走!

+

Hardware da $10 · 10MB di RAM · Avvio in ms · Let's Go, PicoClaw!

Go Hardware @@ -24,135 +24,125 @@ --- -> **PicoClaw** è un progetto open-source indipendente avviato da [Sipeed](https://sipeed.com). È scritto interamente in **Go** — non è un fork di OpenClaw, NanoBot o di qualsiasi altro progetto. +> **PicoClaw** è un progetto open-source indipendente avviato da [Sipeed](https://sipeed.com), scritto interamente in **Go** da zero — non è un fork di OpenClaw, NanoBot o di qualsiasi altro progetto. -🦐 PicoClaw è un assistente IA personale ultra-leggero ispirato a [NanoBot](https://github.com/HKUDS/nanobot), riscritto da zero in Go attraverso un processo di auto-bootstrapping, in cui l'agente IA stesso ha guidato l'intera migrazione architetturale e l'ottimizzazione del codice. +**PicoClaw** è un assistente IA personale ultra-leggero ispirato a [NanoBot](https://github.com/HKUDS/nanobot). È stato riscritto da zero in **Go** attraverso un processo di "auto-bootstrapping" — l'Agent IA stesso ha guidato la migrazione architetturale e l'ottimizzazione del codice. -⚡️ Funziona su hardware da $10 con meno di 10MB di RAM: il 99% di memoria in meno rispetto a OpenClaw e il 98% più economico di un Mac mini! +**Funziona su hardware da $10 con <10MB di RAM** — il 99% di memoria in meno rispetto a OpenClaw e il 98% più economico di un Mac mini! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 SICUREZZA & CANALI UFFICIALI** +> **Avviso di Sicurezza** > -> * **NESSUNA CRYPTO:** PicoClaw non ha **NESSUN** token/coin ufficiale. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **TRUFFA**. -> -> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)**. -> * **Attenzione:** Molti domini `.ai/.org/.com/.net/...` sono registrati da terze parti. -> * **Attenzione:** PicoClaw è in fase di sviluppo iniziale e potrebbe avere problemi di sicurezza di rete non risolti. Non distribuire in ambienti di produzione prima della release v1.0. -> * **Nota:** PicoClaw ha recentemente unito molte PR, il che potrebbe comportare un'impronta di memoria maggiore (10–20MB) nelle ultime versioni. Prevediamo di dare priorità all'ottimizzazione delle risorse non appena il set di funzionalità corrente raggiungerà uno stato stabile. +> * **NESSUNA CRYPTO:** PicoClaw **non** ha emesso token o criptovalute ufficiali. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **truffa**. +> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)** +> * **ATTENZIONE:** Molti domini `.ai/.org/.com/.net/...` sono stati registrati da terze parti. Non fidarti di essi. +> * **NOTA:** PicoClaw è in fase di sviluppo iniziale rapido. Potrebbero esserci problemi di sicurezza non risolti. Non distribuire in produzione prima della v1.0. +> * **NOTA:** PicoClaw ha recentemente unito molte PR. Le build recenti potrebbero usare 10-20MB di RAM. L'ottimizzazione delle risorse è pianificata dopo la stabilizzazione delle funzionalità. ## 📢 Novità -2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), tracciamento dello stato dei sub-agent (`spawn_status`), hot-reload sperimentale del gateway, gate di sicurezza per cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K ⭐**! +2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), query sullo stato dei sub-agent (`spawn_status`), hot-reload sperimentale del Gateway, gate di sicurezza per Cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K Stars**! 2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline di visione, store di memoria JSONL e routing dei modelli. -2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e launcher Web UI. +2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e Web UI Launcher. -2026-02-26 🎉 PicoClaw ha raggiunto **20K stelle** in soli 17 giorni! Arrivate l'orchestrazione automatica dei canali e le interfacce di capacità. +2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive.

Notizie precedenti... -2026-02-16 🎉 PicoClaw ha raggiunto 12K stelle in una settimana! Ruoli di maintainer della community e [roadmap](ROADMAP.md) pubblicati ufficialmente. +2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](ROADMAP.md) pubblicati ufficialmente. -2026-02-13 🎉 PicoClaw ha raggiunto 5000 stelle in 4 giorni! Roadmap del progetto e gruppo sviluppatori in fase di avvio. +2026-02-13 🎉 PicoClaw supera 5000 stelle in 4 giorni! Roadmap del progetto e gruppi sviluppatori in fase di avvio. -2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli agenti IA su hardware da $10 con <10MB di RAM. 🦐 PicoClaw, andiamo! +2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli AI Agent su hardware da $10 con <10MB di RAM. Let's Go, PicoClaw!
## ✨ Caratteristiche -🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo delle funzionalità principali di OpenClaw.* +🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo rispetto a OpenClaw.* 💰 **Costo Minimo**: Abbastanza efficiente da girare su hardware da $10 — il 98% più economico di un Mac mini. -⚡️ **Avvio Fulmineo**: Tempo di avvio 400 volte più veloce, boot in meno di 1 secondo anche su un singolo core a 0,6 GHz. +⚡️ **Avvio Fulmineo**: Avvio 400 volte più veloce. Boot in meno di 1 secondo anche su un singolo core a 0,6 GHz. -🌍 **Vera Portabilità**: Singolo binario autonomo per RISC-V, ARM, MIPS e x86. Un click e si parte! +🌍 **Vera Portabilità**: Singolo binario per RISC-V, ARM, MIPS e x86. Un binario, funziona ovunque! -🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go in modo autonomo — 95% del core generato dall'Agent con perfezionamento umano nel ciclo. +🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go — il 95% del codice core è stato generato da un Agent e perfezionato tramite revisione umana nel ciclo. -🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'agent. +🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'Agent. -👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'agent — codifica base64 automatica per LLM multimodali. +👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'Agent — codifica base64 automatica per LLM multimodali. 🧠 **Routing Intelligente**: Routing dei modelli basato su regole — le query semplici vanno verso modelli leggeri, risparmiando sui costi API. -_*Le versioni recenti potrebbero usare 10–20MB a causa delle fusioni rapide di funzionalità. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._ +_*Le build recenti potrebbero usare 10-20MB a causa delle fusioni rapide di PR. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._ + +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Linguaggio** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **Avvio**
(core 0,8 GHz) | >500s | >30s | **<1s** | -| **Costo** | Mac Mini $599 | La maggior parte degli SBC Linux
~$50 | **Qualsiasi scheda Linux**
**A partire da $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Linguaggio** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Avvio**
(core 0,8 GHz) | >500s | >30s | **<1s** | +| **Costo** | Mac Mini $599 | La maggior parte degli SBC Linux ~$50 | **Qualsiasi scheda Linux**
**a partire da $10** | PicoClaw +
+ +> **[Lista di Compatibilità Hardware](docs/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR! + +

+PicoClaw Hardware Compatibility +

+ ## 🦾 Dimostrazione ### 🛠️ Flussi di Lavoro Standard dell'Assistente - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 Ingegnere Full-Stack

🗂️ Gestione Log & Pianificazione

🔎 Ricerca Web & Apprendimento

Sviluppa • Distribuisci • ScalaPianifica • Automatizza • MemorizzaScopri • Analizza • Tendenze

Modalità Ingegnere Full-Stack

Log & Pianificazione

Ricerca Web & Apprendimento

Sviluppa · Distribuisci · ScalaPianifica · Automatizza · MemorizzaScopri · Analizza · Tendenze
-### 📱 Usa su vecchi telefoni Android - -Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw. Avvio rapido: - -1. **Installa [Termux](https://github.com/termux/termux-app)** (Scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play). -2. **Esegui i comandi** - -```bash -# Scarica l'ultima release da https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard -``` - -Poi segui le istruzioni nella sezione "Avvio Rapido" per completare la configurazione! - -PicoClaw - ### 🐜 Deploy Innovativo a Bassa Impronta PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux! -- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un Assistente Domotico Minimale -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) per la Manutenzione Automatizzata dei Server -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) per il Monitoraggio Intelligente +- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un assistente domotico minimale +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), per la manutenzione automatizzata dei server +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), per la sorveglianza intelligente @@ -160,11 +150,15 @@ PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux! ## 📦 Installazione -### Installa con binario precompilato +### Scarica da picoclaw.io (Consigliato) + +Visita **[picoclaw.io](https://picoclaw.io)** — il sito ufficiale rileva automaticamente la tua piattaforma e fornisce il download con un clic. Non è necessario scegliere manualmente l'architettura. -Scarica il binario per la tua piattaforma dalla pagina delle [Releases](https://github.com/sipeed/picoclaw/releases). +### Scarica il binario precompilato -### Installa dai sorgenti (ultime funzionalità, consigliato per lo sviluppo) +In alternativa, scarica il binario per la tua piattaforma dalla pagina delle [GitHub Releases](https://github.com/sipeed/picoclaw/releases). + +### Compila dai sorgenti (per lo sviluppo) ```bash git clone https://github.com/sipeed/picoclaw.git @@ -172,34 +166,348 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Compila, senza installare +# Compila il binario core make build +# Compila il Web UI Launcher (necessario per la modalità WebUI) +make build-launcher + # Compila per più piattaforme make build-all # Compila per Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) make build-pi-zero -# Compila e Installa +# Compila e installa make install ``` -**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi. +**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi. -## 📚 Documentazione +## 🚀 Guida Rapida -Per guide dettagliate, consulta la documentazione qui sotto. Il README copre solo l'avvio rapido. +### 🌐 WebUI Launcher (Consigliato per Desktop) -| Argomento | Descrizione | -|-----------|-------------| -| 🐳 [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent, configurazione rapida | -| 💬 [App di Chat](docs/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom e altro | -| ⚙️ [Configurazione](docs/it/configuration.md) | Variabili d'ambiente, struttura del workspace, sorgenti delle skill, sandbox di sicurezza, heartbeat | -| 🔌 [Provider & Modelli](docs/providers.md) | 20+ provider LLM, routing dei modelli, configurazione model_list, architettura dei provider | -| 🔄 [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent | -| 🐛 [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni | -| 🔧 [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec | +Il WebUI Launcher fornisce un'interfaccia basata su browser per la configurazione e la chat. È il modo più semplice per iniziare — non è richiesta alcuna conoscenza della riga di comando. + +**Opzione 1: Doppio clic (Desktop)** + +Dopo aver scaricato da [picoclaw.io](https://picoclaw.io), fai doppio clic su `picoclaw-launcher` (o `picoclaw-launcher.exe` su Windows). Il browser si aprirà automaticamente su `http://localhost:18800`. + +**Opzione 2: Riga di comando** + +```bash +picoclaw-launcher +# Apri http://localhost:18800 nel browser +``` + +> [!TIP] +> **Accesso remoto / Docker / VM:** Aggiungi il flag `-public` per ascoltare su tutte le interfacce: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**Per iniziare:** + +Apri il WebUI, poi: **1)** Configura un Provider (aggiungi la tua API key LLM) -> **2)** Configura un Channel (es. Telegram) -> **3)** Avvia il Gateway -> **4)** Chatta! + +Per la documentazione dettagliata del WebUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (alternativa) + +```bash +# 1. Clona questo repo +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Prima esecuzione — genera automaticamente docker/data/config.json poi si ferma +# (si attiva solo quando sia config.json che workspace/ sono assenti) +docker compose -f docker/docker-compose.yml --profile launcher up +# Il container stampa "First-run setup complete." e si ferma. + +# 3. Imposta le tue API key +vim docker/data/config.json + +# 4. Avvia +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Apri http://localhost:18800 +``` + +> **Utenti Docker / VM:** Il Gateway ascolta su `127.0.0.1` per impostazione predefinita. Imposta `PICOCLAW_GATEWAY_HOST=0.0.0.0` o usa il flag `-public` per renderlo accessibile dall'host. + +```bash +# Controlla i log +docker compose -f docker/docker-compose.yml logs -f + +# Ferma +docker compose -f docker/docker-compose.yml --profile launcher down + +# Aggiorna +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher (Consigliato per Headless / SSH) + +Il TUI (Terminal UI) Launcher fornisce un'interfaccia terminale completa per la configurazione e la gestione. Ideale per server, Raspberry Pi e altri ambienti headless. + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**Per iniziare:** + +Usa i menu TUI per: **1)** Configurare un Provider -> **2)** Configurare un Channel -> **3)** Avviare il Gateway -> **4)** Chattare! + +Per la documentazione dettagliata del TUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw. + +**Opzione 1: Termux (disponibile ora)** + +1. Installa [Termux](https://github.com/termux/termux-app) (scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play) +2. Esegui i seguenti comandi: + +```bash +# Scarica l'ultima release +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot fornisce un layout standard del filesystem Linux +``` + +Poi segui la sezione Terminal Launcher qui sotto per completare la configurazione. + +PicoClaw on Termux + +**Opzione 2: APK Install (prossimamente)** + +Un APK Android standalone con WebUI integrato è in sviluppo. Resta sintonizzato! + +
+Terminal Launcher (per ambienti con risorse limitate) + +Per ambienti minimali dove è disponibile solo il binario core `picoclaw` (senza Launcher UI), puoi configurare tutto tramite riga di comando e un file di configurazione JSON. + +**1. Inizializza** + +```bash +picoclaw onboard +``` + +Questo crea `~/.picoclaw/config.json` e la directory workspace. + +**2. Configura** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> Vedi `config/config.example.json` nel repo per un template di configurazione completo con tutte le opzioni disponibili. + +**3. Chatta** + +```bash +# Domanda singola +picoclaw agent -m "Quanto fa 2+2?" + +# Modalità interattiva +picoclaw agent + +# Avvia il gateway per l'integrazione con app di chat +picoclaw gateway +``` + +
+ +## 🔌 Provider (LLM) + +PicoClaw supporta 30+ provider LLM tramite la configurazione `model_list`. Usa il formato `protocollo/modello`: + +| Provider | Protocollo | API Key | Note | +|----------|------------|---------|------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Richiesta | GPT-5.4, GPT-4o, o3, ecc. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Richiesta | Claude Opus 4.6, Sonnet 4.6, ecc. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Richiesta | Gemini 3 Flash, 2.5 Pro, ecc. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Richiesta | 200+ modelli, API unificata | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Richiesta | GLM-4.7, GLM-5, ecc. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Richiesta | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Richiesta | Doubao, modelli Ark | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Richiesta | Qwen3, Qwen-Max, ecc. | +| [Groq](https://console.groq.com/keys) | `groq/` | Richiesta | Inferenza veloce (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Richiesta | Modelli Kimi | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Richiesta | Modelli MiniMax | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Richiesta | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Richiesta | Modelli ospitati NVIDIA | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Richiesta | Inferenza veloce | +| [Novita AI](https://novita.ai/) | `novita/` | Richiesta | Vari modelli open | +| [Ollama](https://ollama.com/) | `ollama/` | Non necessaria | Modelli locali, self-hosted | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Non necessaria | Deploy locale, compatibile OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Variabile | Proxy per 100+ provider | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Richiesta | Deploy Azure enterprise | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login con device code | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+Deploy locale (Ollama, vLLM, ecc.) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](docs/providers.md). + +
+ +## 💬 Channel (App di Chat) + +Parla con il tuo PicoClaw attraverso 17+ piattaforme di messaggistica: + +| Channel | Configurazione | Protocollo | Docs | +|---------|----------------|------------|------| +| **Telegram** | Facile (bot token) | Long polling | [Guida](docs/channels/telegram/README.md) | +| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](docs/channels/discord/README.md) | +| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](docs/chat-apps.md#whatsapp) | +| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](docs/chat-apps.md#weixin) | +| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](docs/channels/qq/README.md) | +| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](docs/channels/slack/README.md) | +| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](docs/channels/matrix/README.md) | +| **DingTalk** | Medio (credenziali client) | Stream | [Guida](docs/channels/dingtalk/README.md) | +| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](docs/channels/feishu/README.md) | +| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](docs/channels/line/README.md) | +| **WeCom Bot** | Medio (webhook URL) | Webhook | [Guida](docs/channels/wecom/wecom_bot/README.md) | +| **WeCom App** | Medio (credenziali aziendali) | Webhook | [Guida](docs/channels/wecom/wecom_app/README.md) | +| **WeCom AI Bot** | Medio (token + AES key) | WebSocket / Webhook | [Guida](docs/channels/wecom/wecom_aibot/README.md) | +| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](docs/chat-apps.md#irc) | +| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](docs/channels/onebot/README.md) | +| **MaixCam** | Facile (abilita) | TCP socket | [Guida](docs/channels/maixcam/README.md) | +| **Pico** | Facile (abilita) | Protocollo nativo | Integrato | +| **Pico Client** | Facile (WebSocket URL) | WebSocket | Integrato | + +> Tutti i channel basati su webhook condividono un singolo server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu usa la modalità WebSocket/SDK e non usa il server HTTP condiviso. + +Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](docs/chat-apps.md). + +## 🔧 Strumenti + +### 🔍 Ricerca Web + +PicoClaw può cercare sul web per fornire informazioni aggiornate. Configura in `tools.web`: + +| Motore di Ricerca | API Key | Piano Gratuito | Link | +|-------------------|---------|----------------|------| +| DuckDuckGo | Non necessaria | Illimitato | Fallback integrato | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Richiesta | 1000 query/giorno | IA, ottimizzato per il cinese | +| [Tavily](https://tavily.com) | Richiesta | 1000 query/mese | Ottimizzato per AI Agent | +| [Brave Search](https://brave.com/search/api) | Richiesta | 2000 query/mese | Veloce e privato | +| [Perplexity](https://www.perplexity.ai) | Richiesta | A pagamento | Ricerca potenziata dall'IA | +| [SearXNG](https://github.com/searxng/searxng) | Non necessaria | Self-hosted | Metasearch engine gratuito | +| [GLM Search](https://open.bigmodel.cn/) | Richiesta | Variabile | Ricerca web Zhipu | + +### ⚙️ Altri Strumenti + +PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](docs/tools_configuration.md) per i dettagli. + +## 🎯 Skill + +Le Skill sono capacità modulari che estendono il tuo Agent. Vengono caricate dai file `SKILL.md` nel tuo workspace. + +**Installa skill da ClawHub:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Configura il token ClawHub** (opzionale, per limiti di frequenza più alti): + +Aggiungi al tuo `config.json`: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](docs/tools_configuration.md#skills-tool). + +## 🔗 MCP (Model Context Protocol) + +PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità del tuo Agent con strumenti e sorgenti di dati esterni. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](docs/tools_configuration.md#mcp-tool). ## ClawdChat Unisciti al Social Network degli Agent @@ -212,12 +520,13 @@ Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singol | Comando | Descrizione | | ------------------------- | ---------------------------------- | | `picoclaw onboard` | Inizializza config & workspace | +| `picoclaw onboard weixin` | Connetti account WeChat tramite QR | | `picoclaw agent -m "..."` | Chatta con l'agent | | `picoclaw agent` | Modalità chat interattiva | | `picoclaw gateway` | Avvia il gateway | | `picoclaw status` | Mostra lo stato | | `picoclaw version` | Mostra le info sulla versione | -| `picoclaw model` | Mostra o cambia il modello predefinito | +| `picoclaw model` | Visualizza o cambia il modello predefinito | | `picoclaw cron list` | Elenca tutti i job pianificati | | `picoclaw cron add ...` | Aggiunge un job pianificato | | `picoclaw cron disable` | Disabilita un job pianificato | @@ -227,24 +536,43 @@ Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singol | `picoclaw migrate` | Migra i dati dalle versioni precedenti | | `picoclaw auth login` | Autenticazione con i provider | -### Task Pianificati / Promemoria +### ⏰ Task Pianificati / Promemoria PicoClaw supporta promemoria pianificati e task ricorrenti tramite lo strumento `cron`: -* **Promemoria una tantum**: "Ricordami tra 10 minuti" → si attiva una volta dopo 10 min -* **Task ricorrenti**: "Ricordami ogni 2 ore" → si attiva ogni 2 ore -* **Espressioni cron**: "Ricordami alle 9 ogni giorno" → usa un'espressione cron +* **Promemoria una tantum**: "Ricordami tra 10 minuti" -> si attiva una volta dopo 10 min +* **Task ricorrenti**: "Ricordami ogni 2 ore" -> si attiva ogni 2 ore +* **Espressioni cron**: "Ricordami alle 9 ogni giorno" -> usa un'espressione cron + +## 📚 Documentazione + +Per guide dettagliate oltre questo README: + +| Argomento | Descrizione | +|-----------|-------------| +| [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent | +| [App di Chat](docs/chat-apps.md) | Tutte le guide di configurazione per 17+ channel | +| [Configurazione](docs/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza | +| [Provider & Modelli](docs/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list | +| [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent | +| [Hooks](docs/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook | +| [Steering](docs/steering.md) | Iniettare messaggi in un loop agent in esecuzione | +| [SubTurn](docs/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita | +| [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni | +| [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill | +| [Compatibilità Hardware](docs/hardware-compatibility.md) | Schede testate, requisiti minimi | ## 🤝 Contribuisci & Roadmap -Le PR sono benvenute! Il codice è volutamente piccolo e leggibile. 🤗 +Le PR sono benvenute! Il codice è volutamente piccolo e leggibile. -Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) completa. +Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida. Gruppo sviluppatori in costruzione, unisciti dopo la tua prima PR accettata! Gruppi utenti: -discord: +Discord: -PicoClaw +WeChat: +WeChat group QR code diff --git a/README.ja.md b/README.ja.md index e5a9275057..3096d40222 100644 --- a/README.ja.md +++ b/README.ja.md @@ -3,7 +3,7 @@

PicoClaw: Go で書かれた超効率 AI アシスタント

-

$10 ハードウェア · <10MB RAM · <1秒起動 · 行くぜ、シャコ!

+

$10 ハードウェア · 10MB RAM · ms 起動 · Let's Go, PicoClaw!

Go Hardware @@ -26,9 +26,9 @@ > **PicoClaw** は [Sipeed](https://sipeed.com) が立ち上げた独立したオープンソースプロジェクトです。完全に **Go 言語**で一から書かれており、OpenClaw、NanoBot、その他のプロジェクトのフォークではありません。 -🦐 PicoClaw は [NanoBot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。Go でゼロからリファクタリングされ、AI エージェント自身がアーキテクチャの移行とコード最適化を推進するセルフブートストラッピングプロセスで構築されました。 +**PicoClaw** は [NanoBot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。**Go** でゼロからリビルドされ、「セルフブートストラッピング」プロセスで構築されました — AI Agent 自身がアーキテクチャの移行とコード最適化を推進しました。 -⚡️ $10 のハードウェアで 10MB 未満の RAM で動作:OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い! +**$10 のハードウェアで 10MB 未満の RAM で動作** — OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い! @@ -46,24 +46,23 @@
> [!CAUTION] -> **🚨 セキュリティ&公式チャンネル** +> **セキュリティに関する注意** > > * **暗号通貨なし:** PicoClaw には公式トークン/コインは**一切ありません**。`pump.fun` やその他の取引プラットフォームでの主張はすべて**詐欺**です。 -> > * **公式ドメイン:** **唯一**の公式サイトは **[picoclaw.io](https://picoclaw.io)**、企業サイトは **[sipeed.com](https://sipeed.com)** です。 -> * **注意:** 多くの `.ai/.org/.com/.net/...` ドメインは第三者によって登録されています。 -> * **注意:** PicoClaw は初期開発段階にあり、未解決のネットワークセキュリティ問題がある可能性があります。v1.0 リリース前に本番環境へのデプロイは避けてください。 +> * **注意:** 多くの `.ai/.org/.com/.net/...` ドメインは第三者によって登録されています。信頼しないでください。 +> * **注記:** PicoClaw は初期開発段階にあり、未解決のネットワークセキュリティ問題がある可能性があります。v1.0 リリース前に本番環境へのデプロイは避けてください。 > * **注記:** PicoClaw は最近多くの PR をマージしており、最新バージョンではメモリフットプリントが大きくなる場合があります(10〜20MB)。機能セットが安定次第、リソース最適化を優先する予定です。 ## 📢 ニュース -2026-03-17 🚀 **v0.2.3 リリース!** システムトレイ UI(Windows & Linux)、サブエージェントステータス追跡(`spawn_status`)、実験的ゲートウェイホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成! +2026-03-17 🚀 **v0.2.3 リリース!** システムトレイ UI(Windows & Linux)、サブエージェントステータス追跡(`spawn_status`)、実験的 Gateway ホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成! -2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート!** MCP プロトコル対応、4 つの新チャネル(Matrix/IRC/WeCom/Discord Proxy)、3 つの新プロバイダー(Kimi/Minimax/Avian)、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。 +2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート!** MCP プロトコル対応、4 つの新 Channel(Matrix/IRC/WeCom/Discord Proxy)、3 つの新 Provider(Kimi/Minimax/Avian)、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。 -2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI ランチャー。 +2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI Launcher。 -2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成!チャネル自動オーケストレーションとケイパビリティインターフェースが実装されました。 +2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成!Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。

過去のニュース... @@ -72,82 +71,71 @@ 2026-02-13 🎉 PicoClaw が 4 日間で 5000 スター達成!プロジェクトロードマップと開発者グループの準備が進行中。 -2026-02-09 🎉 **PicoClaw リリース!** $10 ハードウェアで 10MB 未満の RAM で動く AI エージェントを 1 日で構築。🦐 行くぜ、シャコ! +2026-02-09 🎉 **PicoClaw リリース!** $10 ハードウェアで 10MB 未満の RAM で動く AI Agent を 1 日で構築。Let's Go, PicoClaw!
## ✨ 特徴 -🪶 **超軽量**: メモリフットプリント 10MB 未満 — OpenClaw のコア機能より 99% 小さい。* +🪶 **超軽量**: コアメモリフットプリント 10MB 未満 — OpenClaw より 99% 小さい。* 💰 **最小コスト**: $10 ハードウェアで動作 — Mac mini より 98% 安い。 -⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒未満で起動。 +⚡️ **超高速起動**: 起動時間 400 倍高速。0.6GHz シングルコアでも 1 秒未満で起動。 -🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。ワンクリックで Go! +🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。どこでも動く! -🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。 +🤖 **AI ブートストラップ**: 純粋な Go ネイティブ実装 — コアコードの 95% が Agent によって生成され、人間によるレビューで調整。 -🔌 **MCP 対応**: ネイティブ [Model Context Protocol](https://modelcontextprotocol.io/) 統合 — 任意の MCP サーバーに接続してエージェント機能を拡張。 +🔌 **MCP 対応**: ネイティブ [Model Context Protocol](https://modelcontextprotocol.io/) 統合 — 任意の MCP サーバーに接続して Agent 機能を拡張。 -👁️ **ビジョンパイプライン**: 画像やファイルをエージェントに直接送信 — マルチモーダル LLM 向けの自動 base64 エンコーディング。 +👁️ **ビジョンパイプライン**: 画像やファイルを Agent に直接送信 — マルチモーダル LLM 向けの自動 base64 エンコーディング。 🧠 **スマートルーティング**: ルールベースのモデルルーティング — 簡単なクエリは軽量モデルへ、API コストを節約。 -_*最近のバージョンでは急速な機能マージにより 10〜20MB になる場合があります。リソース最適化は計画中です。起動時間の比較は 0.8GHz シングルコアベンチマークに基づいています(下表参照)。_ +_*最近のバージョンでは急速な PR マージにより 10〜20MB になる場合があります。リソース最適化は計画中です。起動時間の比較は 0.8GHz シングルコアベンチマークに基づいています(下表参照)。_ + +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **言語** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **起動時間**
(0.8GHz コア) | >500秒 | >30秒 | **<1秒** | -| **コスト** | Mac Mini $599 | 大半の Linux SBC
~$50 | **あらゆる Linux ボード**
**最安 $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **言語** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **起動時間**
(0.8GHz コア) | >500秒 | >30秒 | **<1秒** | +| **コスト** | Mac Mini $599 | 大半の Linux ボード ~$50 | **あらゆる Linux ボード**
**最安 $10** | PicoClaw -> 📋 **[ハードウェア互換性リスト](docs/hardware-compatibility.md)** — テスト済みの全ボード一覧($5 RISC-V から Raspberry Pi、Android スマートフォンまで)。お使いのボードが未掲載?PR を送ってください! +
+ +> **[ハードウェア互換性リスト](docs/ja/hardware-compatibility.md)** — テスト済みの全ボード一覧($5 RISC-V から Raspberry Pi、Android スマートフォンまで)。お使いのボードが未掲載?PR を送ってください! + +

+PicoClaw Hardware Compatibility +

## 🦾 デモンストレーション ### 🛠️ スタンダードアシスタントワークフロー - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 フルスタックエンジニア

🗂️ ログ&計画管理

🔎 Web 検索&学習

開発 · デプロイ · スケールスケジュール · 自動化 · メモリ発見 · インサイト · トレンド

フルスタックエンジニアモード

ログ&計画管理

Web 検索&学習

開発 · デプロイ · スケールスケジュール · 自動化 · メモリ発見 · インサイト · トレンド
-### 📱 古い Android スマホで動かす - -10 年前のスマホに第二の人生を!PicoClaw でスマート AI アシスタントに変身させましょう。クイックスタート: - -1. **[Termux](https://github.com/termux/termux-app) をインストール**([GitHub Releases](https://github.com/termux/termux-app/releases) からダウンロード、または F-Droid / Google Play で検索)。 -2. **コマンドを実行** - -```bash -# https://github.com/sipeed/picoclaw/releases から最新リリースをダウンロード -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot で標準的な Linux ファイルシステムレイアウトを提供 -``` - -その後「クイックスタート」セクションの手順に従って設定を完了してください! - -PicoClaw - ### 🐜 革新的な省フットプリントデプロイ PicoClaw はほぼすべての Linux デバイスにデプロイできます! @@ -178,9 +166,12 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# ビルド(インストール不要) +# コアバイナリをビルド make build +# Web UI Launcher をビルド(WebUI モードに必要) +make build-launcher + # 複数プラットフォーム向けビルド make build-all @@ -193,20 +184,330 @@ make install **Raspberry Pi Zero 2 W:** OS に合ったバイナリを使用してください:32-bit Raspberry Pi OS → `make build-linux-arm`、64-bit → `make build-linux-arm64`。または `make build-pi-zero` で両方をビルド。 -## 📚 ドキュメント +## 🚀 クイックスタートガイド -詳細なガイドは以下のドキュメントを参照してください。この README はクイックスタートのみをカバーしています。 +### 🌐 WebUI Launcher(デスクトップ向け推奨) -| トピック | 説明 | -|---------|------| -| 🐳 [Docker & クイックスタート](docs/ja/docker.md) | Docker Compose セットアップ、Launcher/Agent モード、クイックスタート設定 | -| 💬 [チャットアプリ](docs/ja/chat-apps.md) | Telegram、Discord、WhatsApp、Matrix、QQ、Slack、IRC、DingTalk、LINE、Feishu、WeCom など | -| ⚙️ [設定](docs/ja/configuration.md) | 環境変数、ワークスペース構成、スキルソース、セキュリティサンドボックス、ハートビート | -| 🔌 [プロバイダー&モデル](docs/ja/providers.md) | 20 以上の LLM プロバイダー、モデルルーティング、model_list 設定、プロバイダーアーキテクチャ | -| 🔄 [Spawn & 非同期タスク](docs/ja/spawn-tasks.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション | -| 🐛 [トラブルシューティング](docs/ja/troubleshooting.md) | よくある問題と解決策 | -| 🔧 [ツール設定](docs/ja/tools_configuration.md) | ツールごとの有効/無効、exec ポリシー | -| 📋 [ハードウェア互換性](docs/hardware-compatibility.md) | テスト済みボード、最小要件、ボードの追加方法 | +WebUI Launcher はブラウザベースの設定・チャットインターフェースを提供します。コマンドラインの知識不要で、最も簡単に始められる方法です。 + +**オプション 1: ダブルクリック(デスクトップ)** + +[picoclaw.io](https://picoclaw.io) からダウンロード後、`picoclaw-launcher`(Windows では `picoclaw-launcher.exe`)をダブルクリックしてください。ブラウザが自動的に `http://localhost:18800` を開きます。 + +**オプション 2: コマンドライン** + +```bash +picoclaw-launcher +# ブラウザで http://localhost:18800 を開く +``` + +> [!TIP] +> **リモートアクセス / Docker / VM:** すべてのインターフェースでリッスンするには `-public` フラグを追加してください: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**始め方:** + +WebUI を開いたら:**1)** Provider を設定(LLM API キーを追加)→ **2)** Channel を設定(例:Telegram)→ **3)** Gateway を起動 → **4)** チャット! + +WebUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。 + +
+Docker(代替手段) + +```bash +# 1. このリポジトリをクローン +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. 初回実行 — docker/data/config.json を自動生成して終了 +# (config.json と workspace/ の両方が存在しない場合のみ実行) +docker compose -f docker/docker-compose.yml --profile launcher up +# コンテナが "First-run setup complete." を出力して停止します。 + +# 3. API キーを設定 +vim docker/data/config.json + +# 4. 起動 +docker compose -f docker/docker-compose.yml --profile launcher up -d +# http://localhost:18800 を開く +``` + +> **Docker / VM ユーザー:** Gateway はデフォルトで `127.0.0.1` でリッスンします。ホストからアクセスできるようにするには `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`-public` フラグを使用してください。 + +```bash +# ログを確認 +docker compose -f docker/docker-compose.yml logs -f + +# 停止 +docker compose -f docker/docker-compose.yml --profile launcher down + +# 更新 +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher(ヘッドレス / SSH 向け推奨) + +TUI(Terminal UI)Launcher は設定と管理のためのフル機能ターミナルインターフェースを提供します。サーバー、Raspberry Pi、その他のヘッドレス環境に最適です。 + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**始め方:** + +TUI メニューを使って:**1)** Provider を設定 → **2)** Channel を設定 → **3)** Gateway を起動 → **4)** チャット! + +TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。 + +### 📱 Android + +10 年前のスマホに第二の人生を!PicoClaw でスマート AI アシスタントに変身させましょう。 + +**オプション 1: Termux(現在利用可能)** + +1. [Termux](https://github.com/termux/termux-app) をインストール([GitHub Releases](https://github.com/termux/termux-app/releases) からダウンロード、または F-Droid / Google Play で検索) +2. 以下のコマンドを実行: + +```bash +# 最新リリースをダウンロード +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot で標準的な Linux ファイルシステムレイアウトを提供 +``` + +その後、下記の Terminal Launcher セクションの手順に従って設定を完了してください。 + +PicoClaw on Termux + +**オプション 2: APK インストール(近日公開)** + +内蔵 WebUI を備えたスタンドアロン Android APK を開発中です。お楽しみに! + +
+Terminal Launcher(リソース制約環境向け) + +`picoclaw` コアバイナリのみが利用可能な最小環境(Launcher UI なし)では、コマンドラインと JSON 設定ファイルですべてを設定できます。 + +**1. 初期化** + +```bash +picoclaw onboard +``` + +`~/.picoclaw/config.json` とワークスペースディレクトリが作成されます。 + +**2. 設定** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> 利用可能なすべてのオプションを含む完全な設定テンプレートは、リポジトリの `config/config.example.json` を参照してください。 + +**3. チャット** + +```bash +# ワンショット質問 +picoclaw agent -m "What is 2+2?" + +# インタラクティブモード +picoclaw agent + +# チャットアプリ統合用 Gateway を起動 +picoclaw gateway +``` + +
+ +## 🔌 Provider(LLM) + +PicoClaw は `model_list` 設定を通じて 30 以上の LLM Provider をサポートしています。`protocol/model` 形式を使用してください: + +| Provider | Protocol | API キー | 備考 | +|----------|----------|---------|------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必須 | GPT-5.4、GPT-4o、o3 など | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必須 | Claude Opus 4.6、Sonnet 4.6 など | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必須 | Gemini 3 Flash、2.5 Pro など | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必須 | 200 以上のモデル、統合 API | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必須 | GLM-4.7、GLM-5 など | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必須 | DeepSeek-V3、DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | 必須 | Doubao、Ark モデル | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必須 | Qwen3、Qwen-Max など | +| [Groq](https://console.groq.com/keys) | `groq/` | 必須 | 高速推論(Llama、Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必須 | Kimi モデル | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必須 | MiniMax モデル | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必須 | Mistral Large、Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必須 | NVIDIA ホスティングモデル | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必須 | 高速推論 | +| [Novita AI](https://novita.ai/) | `novita/` | 必須 | 各種オープンモデル | +| [Ollama](https://ollama.com/) | `ollama/` | 不要 | ローカルモデル、セルフホスト | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | 不要 | ローカルデプロイ、OpenAI 互換 | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 場合による | 100 以上の Provider のプロキシ | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必須 | エンタープライズ Azure デプロイ | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | デバイスコードログイン | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+ローカルデプロイ(Ollama、vLLM など) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.md) を参照してください。 + +
+ +## 💬 Channel(チャットアプリ) + +17 以上のメッセージングプラットフォームで PicoClaw と会話できます: + +| Channel | セットアップ | Protocol | ドキュメント | +|---------|------------|----------|------------| +| **Telegram** | 簡単(bot トークン) | Long polling | [ガイド](docs/channels/telegram/README.ja.md) | +| **Discord** | 簡単(bot トークン + intents) | WebSocket | [ガイド](docs/channels/discord/README.ja.md) | +| **WhatsApp** | 簡単(QR スキャンまたは bridge URL) | Native / Bridge | [ガイド](docs/ja/chat-apps.md#whatsapp) | +| **微信 (Weixin)** | 簡単(QR スキャン) | iLink API | [ガイド](docs/ja/chat-apps.md#weixin) | +| **QQ** | 簡単(AppID + AppSecret) | WebSocket | [ガイド](docs/channels/qq/README.ja.md) | +| **Slack** | 簡単(bot + app トークン) | Socket Mode | [ガイド](docs/channels/slack/README.ja.md) | +| **Matrix** | 中級(homeserver + トークン) | Sync API | [ガイド](docs/channels/matrix/README.ja.md) | +| **DingTalk** | 中級(クライアント認証情報) | Stream | [ガイド](docs/channels/dingtalk/README.ja.md) | +| **Feishu / Lark** | 中級(App ID + Secret) | WebSocket/SDK | [ガイド](docs/channels/feishu/README.ja.md) | +| **LINE** | 中級(認証情報 + webhook) | Webhook | [ガイド](docs/channels/line/README.ja.md) | +| **WeCom Bot** | 中級(webhook URL) | Webhook | [ガイド](docs/channels/wecom/wecom_bot/README.ja.md) | +| **WeCom App** | 中級(corp 認証情報) | Webhook | [ガイド](docs/channels/wecom/wecom_app/README.ja.md) | +| **WeCom AI Bot** | 中級(トークン + AES キー) | WebSocket / Webhook | [ガイド](docs/channels/wecom/wecom_aibot/README.ja.md) | +| **IRC** | 中級(サーバー + nick) | IRC protocol | [ガイド](docs/ja/chat-apps.md#irc) | +| **OneBot** | 中級(WebSocket URL) | OneBot v11 | [ガイド](docs/channels/onebot/README.ja.md) | +| **MaixCam** | 簡単(有効化) | TCP socket | [ガイド](docs/channels/maixcam/README.ja.md) | +| **Pico** | 簡単(有効化) | Native protocol | 内蔵 | +| **Pico Client** | 簡単(WebSocket URL) | WebSocket | 内蔵 | + +> webhook ベースのすべての Channel は単一の Gateway HTTP サーバー(`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`)を共有します。Feishu は WebSocket/SDK モードを使用し、共有 HTTP サーバーを使用しません。 + +Channel の詳細なセットアップ手順は [チャットアプリ設定](docs/ja/chat-apps.md) を参照してください。 + +## 🔧 ツール + +### 🔍 Web 検索 + +PicoClaw は最新情報を提供するために Web を検索できます。`tools.web` で設定してください: + +| 検索エンジン | API キー | 無料枠 | リンク | +|------------|---------|--------|-------| +| DuckDuckGo | 不要 | 無制限 | 内蔵フォールバック | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必須 | 1000 クエリ/日 | AI 搭載、中国語に最適化 | +| [Tavily](https://tavily.com) | 必須 | 1000 クエリ/月 | AI Agent 向けに最適化 | +| [Brave Search](https://brave.com/search/api) | 必須 | 2000 クエリ/月 | 高速でプライベート | +| [Perplexity](https://www.perplexity.ai) | 必須 | 有料 | AI 搭載検索 | +| [SearXNG](https://github.com/searxng/searxng) | 不要 | セルフホスト | 無料メタ検索エンジン | +| [GLM Search](https://open.bigmodel.cn/) | 必須 | 場合による | Zhipu Web 検索 | + +### ⚙️ その他のツール + +PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](docs/ja/tools_configuration.md) を参照してください。 + +## 🎯 Skill + +Skill は Agent を拡張するモジュール型の機能です。ワークスペース内の `SKILL.md` ファイルから読み込まれます。 + +**ClawHub から Skill をインストール:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**ClawHub トークンを設定**(オプション、レート制限を上げるため): + +`config.json` に追加: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +詳細は [ツール設定 - Skill](docs/ja/tools_configuration.md#skills-tool) を参照してください。 + +## 🔗 MCP(Model Context Protocol) + +PicoClaw は [MCP](https://modelcontextprotocol.io/) をネイティブサポートしています — 任意の MCP サーバーに接続して、外部ツールやデータソースで Agent の機能を拡張できます。 + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +MCP の完全な設定(stdio、SSE、HTTP トランスポート、Tool Discovery)は [ツール設定 - MCP](docs/ja/tools_configuration.md#mcp-tool) を参照してください。 ## ClawdChat エージェントソーシャルネットワークに参加 @@ -219,22 +520,23 @@ CLI または統合チャットアプリからメッセージを 1 つ送るだ | コマンド | 説明 | | ------------------------- | ------------------------------ | | `picoclaw onboard` | 設定&ワークスペースの初期化 | -| `picoclaw agent -m "..."` | エージェントとチャット | +| `picoclaw onboard weixin` | WeChat アカウントを QR で接続 | +| `picoclaw agent -m "..."` | Agent とチャット | | `picoclaw agent` | インタラクティブチャットモード | -| `picoclaw gateway` | ゲートウェイを起動 | +| `picoclaw gateway` | Gateway を起動 | | `picoclaw status` | ステータスを表示 | | `picoclaw version` | バージョン情報を表示 | +| `picoclaw model` | デフォルトモデルの表示・切替 | | `picoclaw cron list` | スケジュールジョブ一覧 | | `picoclaw cron add ...` | スケジュールジョブを追加 | | `picoclaw cron disable` | スケジュールジョブを無効化 | | `picoclaw cron remove` | スケジュールジョブを削除 | -| `picoclaw skills list` | インストール済みスキル一覧 | -| `picoclaw skills install` | スキルをインストール | +| `picoclaw skills list` | インストール済み Skill 一覧 | +| `picoclaw skills install` | Skill をインストール | | `picoclaw migrate` | 旧バージョンからデータを移行 | -| `picoclaw auth login` | プロバイダーへの認証 | -| `picoclaw model` | デフォルトモデルの表示・切替 | +| `picoclaw auth login` | Provider への認証 | -### スケジュールタスク / リマインダー +### ⏰ スケジュールタスク / リマインダー PicoClaw は `cron` ツールによるスケジュールリマインダーと定期タスクをサポートしています: @@ -242,16 +544,35 @@ PicoClaw は `cron` ツールによるスケジュールリマインダーと定 * **定期タスク**: 「2時間ごとにリマインド」→ 2時間ごとにトリガー * **Cron 式**: 「毎日9時にリマインド」→ cron 式を使用 +## 📚 ドキュメント + +この README を超えた詳細なガイドについては: + +| トピック | 説明 | +|---------|------| +| [Docker & クイックスタート](docs/ja/docker.md) | Docker Compose セットアップ、Launcher/Agent モード | +| [チャットアプリ](docs/ja/chat-apps.md) | 17 以上の Channel セットアップガイド | +| [設定](docs/ja/configuration.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス | +| [Provider とモデル](docs/ja/providers.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 | +| [Spawn & 非同期タスク](docs/ja/spawn-tasks.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション | +| [Hook システム](docs/hooks/README.md) | イベント駆動 Hook:オブザーバー、インターセプター、承認 Hook | +| [Steering](docs/steering.md) | 実行中の Agent ループにメッセージを注入 | +| [SubTurn](docs/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル | +| [トラブルシューティング](docs/ja/troubleshooting.md) | よくある問題と解決策 | +| [ツール設定](docs/ja/tools_configuration.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill | +| [ハードウェア互換性](docs/ja/hardware-compatibility.md) | テスト済みボード、最小要件 | + ## 🤝 コントリビュート&ロードマップ -PR 歓迎!コードベースは意図的に小さく読みやすくしています。🤗 +PR 歓迎!コードベースは意図的に小さく読みやすくしています。 -完全な[コミュニティロードマップ](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md)をご覧ください。 +[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。 開発者グループ構築中、最初の PR がマージされたら参加できます! ユーザーグループ: -discord: +Discord: -PicoClaw +WeChat: +WeChat group QR code diff --git a/README.md b/README.md index 994e4d13a8..e25366ef85 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@
- PicoClaw +PicoClaw -

PicoClaw: Ultra-Efficient AI Assistant in Go

+

PicoClaw: Ultra-Efficient AI Assistant in Go

-

$10 Hardware · <10MB RAM · <1s Boot · 皮皮虾,我们走!

+

$10 Hardware · 10MB RAM · ms Boot · Let's Go, PicoClaw!

Go Hardware @@ -24,141 +24,129 @@ --- -> **PicoClaw** is an independent open-source project initiated by [Sipeed](https://sipeed.com). It is written entirely in **Go** — not a fork of OpenClaw, NanoBot, or any other project. +> **PicoClaw** is an independent open-source project initiated by [Sipeed](https://sipeed.com), written entirely in **Go** from scratch — not a fork of OpenClaw, NanoBot, or any other project. -🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [NanoBot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization. +**PicoClaw** is an ultra-lightweight personal AI assistant inspired by [NanoBot](https://github.com/HKUDS/nanobot). It was rebuilt from the ground up in **Go** through a "self-bootstrapping" process — the AI Agent itself drove the architecture migration and code optimization. -⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini! +**Runs on $10 hardware with <10MB RAM** — that's 99% less memory than OpenClaw and 98% cheaper than a Mac mini! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明** -> -> * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**. +> **Security Notice** > +> * **NO CRYPTO:** PicoClaw has **not** issued any official tokens or cryptocurrency. All claims on `pump.fun` or other trading platforms are **scams**. > * **OFFICIAL DOMAIN:** The **ONLY** official website is **[picoclaw.io](https://picoclaw.io)**, and company website is **[sipeed.com](https://sipeed.com)** -> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties. -> * **Warning:** picoclaw is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release. -> * **Note:** picoclaw has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state. +> * **BEWARE:** Many `.ai/.org/.com/.net/...` domains have been registered by third parties. Do not trust them. +> * **NOTE:** PicoClaw is in early rapid development. There may be unresolved security issues. Do not deploy to production before v1.0. +> * **NOTE:** PicoClaw has recently merged many PRs. Recent builds may use 10-20MB RAM. Resource optimization is planned after feature stabilization. ## 📢 News -2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status tracking (`spawn_status`), experimental gateway hot-reload, cron security gates, and 2 security fixes. PicoClaw now at **25K ⭐**! +2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status query (`spawn_status`), experimental Gateway hot-reload, Cron security gating, and 2 security fixes. PicoClaw has reached **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, and model routing. +2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, model routing. -2026-02-28 📦 **v0.2.0** released with Docker Compose support and Web UI launcher. +2026-02-28 📦 **v0.2.0** released with Docker Compose and Web UI Launcher support. -2026-02-26 🎉 PicoClaw hit **20K stars** in just 17 days! Channel auto-orchestration and capability interfaces landed. +2026-02-26 🎉 PicoClaw hits **20K Stars** in just 17 days! Channel auto-orchestration and capability interfaces are live.

-Older news... +Earlier news... -2026-02-16 🎉 PicoClaw hit 12K stars in one week! Community maintainer roles and [roadmap](ROADMAP.md) officially posted. +2026-02-16 🎉 PicoClaw breaks 12K Stars in one week! Community maintainer roles and [Roadmap](ROADMAP.md) officially launched. -2026-02-13 🎉 PicoClaw hit 5000 stars in 4 days! Project Roadmap and Developer Group setup underway. +2026-02-13 🎉 PicoClaw breaks 5000 Stars in 4 days! Project roadmap and developer groups in progress. -2026-02-09 🎉 **PicoClaw Launched!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw,Let's Go! +2026-02-09 🎉 **PicoClaw Released!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. Let's Go, PicoClaw!
## ✨ Features -🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than OpenClaw core functionality.* +🪶 **Ultra-lightweight**: Core memory footprint <10MB — 99% smaller than OpenClaw.* + +💰 **Minimal cost**: Efficient enough to run on $10 hardware — 98% cheaper than a Mac mini. -💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini. +⚡️ **Lightning-fast boot**: 400x faster startup. Boots in <1s even on a 0.6GHz single-core processor. -⚡️ **Lightning Fast**: 400X Faster startup time, boot in <1 second even on 0.6GHz single core. +🌍 **Truly portable**: Single binary across RISC-V, ARM, MIPS, and x86 architectures. One binary, runs everywhere! -🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, MIPS, and x86, One-click to Go! +🤖 **AI-bootstrapped**: Pure Go native implementation — 95% of core code was generated by an Agent and fine-tuned through human-in-the-loop review. -🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement. +🔌 **MCP support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend Agent capabilities. -🔌 **MCP Support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend agent capabilities. +👁️ **Vision pipeline**: Send images and files directly to the Agent — automatic base64 encoding for multimodal LLMs. -👁️ **Vision Pipeline**: Send images and files directly to the agent — automatic base64 encoding for multimodal LLMs. +🧠 **Smart routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs. -🧠 **Smart Routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs. +_*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is planned. Boot speed comparison based on 0.8GHz single-core benchmarks (see table below)._ -_*Recent versions may use 10–20MB due to rapid feature merges. Resource optimization is planned. Startup comparison based on 0.8GHz single-core benchmarks (see table below)._ +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Language** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **Startup**
(0.8GHz core) | >500s | >30s | **<1s** | -| **Cost** | Mac Mini $599 | Most Linux SBC
~$50 | **Any Linux Board**
**As low as $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Language** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Boot time**
(0.8GHz core) | >500s | >30s | **<1s** | +| **Cost** | Mac Mini $599 | Most Linux boards ~$50 | **Any Linux board**
**from $10** | PicoClaw -> 📋 **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR! +
+ +> **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR! + +

+PicoClaw Hardware Compatibility +

## 🦾 Demonstration ### 🛠️ Standard Assistant Workflows - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 Full-Stack Engineer

🗂️ Logging & Planning Management

🔎 Web Search & Learning

Develop • Deploy • ScaleSchedule • Automate • MemoryDiscovery • Insights • Trends

Full-Stack Engineer Mode

Logging & Planning

Web Search & Learning

Develop · Deploy · ScaleSchedule · Automate · RememberDiscover · Insights · Trends
-### 📱 Run on old Android Phones - -Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start: - -1. **Install [Termux](https://github.com/termux/termux-app)** (Download from [GitHub Releases](https://github.com/termux/termux-app/releases), or search in F-Droid / Google Play). -2. **Execute cmds** - -```bash -# Download the latest release from https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem layout -``` - -And then follow the instructions in the "Quick Start" section to complete the configuration! +### 🐜 Innovative Low-Footprint Deployment -PicoClaw +PicoClaw can be deployed on virtually any Linux device! -### 🐜 Innovative Low-Footprint Deploy - -PicoClaw can be deployed on almost any Linux device! - -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring +- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) edition, for a minimal home assistant +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), for automated server operations +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), for smart surveillance -🌟 More Deployment Cases Await! +🌟 More Deployment Cases Await! ## 📦 Install @@ -178,1253 +166,413 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Build, no need to install +# Build core binary make build +# Build Web UI Launcher (required for WebUI mode) +make build-launcher + # 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 +# 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`; 64-bit → `make build-linux-arm64`. Or run `make build-pi-zero` to build both. - -## 📚 Documentation +**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Or run `make build-pi-zero` to build both. -For detailed guides, see the docs below. The README covers quick start only. +## 🚀 Quick Start Guide -```bash -# 1. Clone this repo -git clone https://github.com/sipeed/picoclaw.git -cd picoclaw +### 🌐 WebUI Launcher (Recommended for Desktop) -# 2. First run — auto-generates docker/data/config.json then exits -docker compose -f docker/docker-compose.yml --profile gateway up -# The container prints "First-run setup complete." and stops. +The WebUI Launcher provides a browser-based interface for configuration and chat. This is the easiest way to get started — no command-line knowledge required. -# 3. Set your API keys -vim docker/data/config.json # Set provider API keys, bot tokens, etc. +**Option 1: Double-click (Desktop)** -# 4. Start -docker compose -f docker/docker-compose.yml --profile gateway up -d -``` +After downloading from [picoclaw.io](https://picoclaw.io), double-click `picoclaw-launcher` (or `picoclaw-launcher.exe` on Windows). Your browser will open automatically at `http://localhost:18800`. -> [!TIP] -> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`. +**Option 2: Command line** ```bash -# 5. Check logs -docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway - -# 6. Stop -docker compose -f docker/docker-compose.yml --profile gateway down +picoclaw-launcher +# Open http://localhost:18800 in your browser ``` -### Launcher Mode (Web Console) +> [!TIP] +> **Remote access / Docker / VM:** Add the `-public` flag to listen on all interfaces: +> ```bash +> picoclaw-launcher -public +> ``` -The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat. +

+WebUI Launcher +

-```bash -docker compose -f docker/docker-compose.yml --profile launcher up -d -``` +**Getting started:** -Open http://localhost:18800 in your browser. The launcher manages the gateway process automatically. +Open the WebUI, then: **1)** Configure a Provider (add your LLM API key) -> **2)** Configure a Channel (e.g., Telegram) -> **3)** Start the Gateway -> **4)** Chat! -> [!WARNING] -> The web console does not yet support authentication. Avoid exposing it to the public internet. +For detailed WebUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io). -### Agent Mode (One-shot) +
+Docker (alternative) ```bash -# Ask a question -docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?" +# 1. Clone this repo +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw -# Interactive mode -docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -``` +# 2. First run — auto-generates docker/data/config.json then exits +# (only triggers when both config.json and workspace/ are missing) +docker compose -f docker/docker-compose.yml --profile launcher up +# The container prints "First-run setup complete." and stops. -### Update +# 3. Set your API keys +vim docker/data/config.json -```bash -docker compose -f docker/docker-compose.yml pull -docker compose -f docker/docker-compose.yml --profile gateway up -d +# 4. Start +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Open http://localhost:18800 ``` -### 🚀 Quick Start - -> [!TIP] -> Set your API Key in `~/.picoclaw/config.json`. Get API Keys: [Volcengine (CodingPlan)](https://console.volcengine.com) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Web search is optional — get a free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month). - -**1. Initialize** +> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host. ```bash -picoclaw onboard -``` +# Check logs +docker compose -f docker/docker-compose.yml logs -f -**2. Configure** (`~/.picoclaw/config.json`) +# Stop +docker compose -f docker/docker-compose.yml --profile launcher down -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "model_name": "gpt-5.4", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_key": "sk-your-api-key" - }, - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_key": "your-api-key", - "request_timeout": 300 - }, - { - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "api_key": "your-anthropic-key" - } - ], - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "tavily": { - "enabled": false, - "api_key": "YOUR_TAVILY_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - }, - "perplexity": { - "enabled": false, - "api_key": "YOUR_PERPLEXITY_API_KEY", - "max_results": 5 - }, - "searxng": { - "enabled": false, - "base_url": "http://your-searxng-instance:8888", - "max_results": 5 - } - } - } -} +# Update +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d ``` -> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details. -> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s). - -**3. Get API Keys** - -* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -* **Web Search** (optional): - * [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month) - * [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface - * [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed) - * [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month) - * DuckDuckGo - Built-in fallback (no API key required) +
-> **Note**: See `config.example.json` for a complete configuration template. +### 💻 TUI Launcher (Recommended for Headless / SSH) -**4. Chat** +The TUI (Terminal UI) Launcher provides a full-featured terminal interface for configuration and management. Ideal for servers, Raspberry Pi, and other headless environments. ```bash -picoclaw agent -m "What is 2+2?" +picoclaw-launcher-tui ``` -That's it! You have a working AI assistant in 2 minutes. - ---- - -## 💬 Chat Apps - -Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, or WeCom - -> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server. - -| Channel | Setup | -| ------------ | ---------------------------------- | -| **Telegram** | Easy (just a token) | -| **Discord** | Easy (bot token + intents) | -| **WhatsApp** | Easy (native: QR scan; or bridge URL) | -| **Weixin** | Easy (Native QR scan) | -| **Matrix** | Medium (homeserver + bot access token) | -| **QQ** | Easy (AppID + AppSecret) | -| **DingTalk** | Medium (app credentials) | -| **LINE** | Medium (credentials + webhook URL) | -| **WeCom AI Bot** | Medium (Token + AES key) | +

+TUI Launcher +

-
-Telegram (Recommended) +**Getting started:** -**1. Create a bot** +Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat! -* Open Telegram, search `@BotFather` -* Send `/newbot`, follow prompts -* Copy the token +For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io). -**2. Configure** +### 📱 Android -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` +Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. -> Get your user ID from `@userinfobot` on Telegram. +**Option 1: Termux (available now)** -**3. Run** +1. Install [Termux](https://github.com/termux/termux-app) (download from [GitHub Releases](https://github.com/termux/termux-app/releases), or search in F-Droid / Google Play) +2. Run the following commands: ```bash -picoclaw gateway +# Download the latest release +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem layout ``` -**4. Telegram command menu (auto-registered at startup)** +Then follow the Terminal Launcher section below to complete configuration. -PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example `/start`, `/help`, `/show`, `/list`) so command menu and runtime behavior stay in sync. -Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor. +PicoClaw on Termux -If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background. +**Option 2: APK Install (coming soon)** -
+A standalone Android APK with built-in WebUI is in development. Stay tuned!
-Discord - -**1. Create a bot** - -* Go to -* Create an application → Bot → Add Bot -* Copy the bot token +Terminal Launcher (for resource-constrained environments) -**2. Enable intents** +For minimal environments where only the `picoclaw` core binary is available (no Launcher UI), you can configure everything via the command line and a JSON config file. -* In the Bot settings, enable **MESSAGE CONTENT INTENT** -* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data - -**3. Get your User ID** -* Discord Settings → Advanced → enable **Developer Mode** -* Right-click your avatar → **Copy User ID** - -**4. Configure** +**1. Initialize** -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} +```bash +picoclaw onboard ``` -**5. Invite the bot** - -* OAuth2 → URL Generator -* Scopes: `bot` -* Bot Permissions: `Send Messages`, `Read Message History` -* Open the generated invite URL and add the bot to your server +This creates `~/.picoclaw/config.json` and the workspace directory. -**Optional: Group trigger mode** - -By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add: +**2. Configure** (`~/.picoclaw/config.json`) ```json { - "channels": { - "discord": { - "group_trigger": { "mention_only": true } + "agents": { + "defaults": { + "model_name": "gpt-5.4" } - } -} -``` - -You can also trigger by keyword prefixes (e.g. `!bot`): - -```json -{ - "channels": { - "discord": { - "group_trigger": { "prefixes": ["!bot"] } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" } - } + ] } ``` -**6. Run** - -```bash -picoclaw gateway -``` - -
- -
-WhatsApp (native via whatsmeow) +> See `config/config.example.json` in the repo for a complete configuration template with all available options. -PicoClaw can connect to WhatsApp in two ways: +**3. Chat** -- **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. +```bash +# One-shot question +picoclaw agent -m "What is 2+2?" -**Configure (native)** +# Interactive mode +picoclaw agent -```json -{ - "channels": { - "whatsapp": { - "enabled": true, - "use_native": true, - "session_store_path": "", - "allow_from": [] - } - } -} +# Start gateway for chat app integration +picoclaw gateway ``` -If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices. -
-
-Weixin (WeChat Personal) - -PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API. +## 🔌 Providers (LLM) + +PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use the `protocol/model` format: + +| Provider | Protocol | API Key | Notes | +|----------|----------|---------|-------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Required | GPT-5.4, GPT-4o, o3, etc. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Required | Claude Opus 4.6, Sonnet 4.6, etc. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Required | Gemini 3 Flash, 2.5 Pro, etc. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Required | 200+ models, unified API | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Required | GLM-4.7, GLM-5, etc. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Required | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Required | Doubao, Ark models | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Required | Qwen3, Qwen-Max, etc. | +| [Groq](https://console.groq.com/keys) | `groq/` | Required | Fast inference (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Required | Kimi models | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Required | MiniMax models | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Required | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Required | NVIDIA hosted models | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Required | Fast inference | +| [Novita AI](https://novita.ai/) | `novita/` | Required | Various open models | +| [Ollama](https://ollama.com/) | `ollama/` | Not needed | Local models, self-hosted | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Not needed | Local deployment, OpenAI-compatible | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varies | Proxy for 100+ providers | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Required | Enterprise Azure deployment | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Device code login | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | -**1. Login** -Run the interactive QR login flow: -```bash -picoclaw onboard weixin -``` -Scan the printed QR code with your WeChat mobile app. On success, the token is saved to your config. +
+Local deployment (Ollama, vLLM, etc.) -**2. Configure** -(Optional) Update `allow_from` with your WeChat User ID to restrict who can message the bot: +**Ollama:** ```json { - "channels": { - "weixin": { - "enabled": true, - "token": "YOUR_TOKEN", - "allow_from": ["YOUR_USER_ID"] + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" } - } + ] } ``` -**3. Run** -```bash -picoclaw gateway -``` - -
- -
-QQ - -**1. Create a bot** - -- Go to [QQ Open Platform](https://q.qq.com/#) -- Create an application → Get **AppID** and **AppSecret** - -**2. Configure** - +**vLLM:** ```json { - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" } - } + ] } ``` -> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access. - -**3. Run** - -```bash -picoclaw gateway -``` +For full provider configuration details, see [Providers & Models](docs/providers.md).
-
-DingTalk +## 💬 Channels (Chat Apps) -**1. Create a bot** +Talk to your PicoClaw through 17+ messaging platforms: -* Go to [Open Platform](https://open.dingtalk.com/) -* Create an internal app -* Copy Client ID and Client Secret +| Channel | Setup | Protocol | Docs | +|---------|-------|----------|------| +| **Telegram** | Easy (bot token) | Long polling | [Guide](docs/channels/telegram/README.md) | +| **Discord** | Easy (bot token + intents) | WebSocket | [Guide](docs/channels/discord/README.md) | +| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/chat-apps.md#whatsapp) | +| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/chat-apps.md#weixin) | +| **QQ** | Easy (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.md) | +| **Slack** | Easy (bot + app token) | Socket Mode | [Guide](docs/channels/slack/README.md) | +| **Matrix** | Medium (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.md) | +| **DingTalk** | Medium (client credentials) | Stream | [Guide](docs/channels/dingtalk/README.md) | +| **Feishu / Lark** | Medium (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.md) | +| **LINE** | Medium (credentials + webhook) | Webhook | [Guide](docs/channels/line/README.md) | +| **WeCom Bot** | Medium (webhook URL) | Webhook | [Guide](docs/channels/wecom/wecom_bot/README.md) | +| **WeCom App** | Medium (corp credentials) | Webhook | [Guide](docs/channels/wecom/wecom_app/README.md) | +| **WeCom AI Bot** | Medium (token + AES key) | WebSocket / Webhook | [Guide](docs/channels/wecom/wecom_aibot/README.md) | +| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/chat-apps.md#irc) | +| **OneBot** | Medium (WebSocket URL) | OneBot v11 | [Guide](docs/channels/onebot/README.md) | +| **MaixCam** | Easy (enable) | TCP socket | [Guide](docs/channels/maixcam/README.md) | +| **Pico** | Easy (enable) | Native protocol | Built-in | +| **Pico Client** | Easy (WebSocket URL) | WebSocket | Built-in | -**2. Configure** +> All webhook-based channels share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server. -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` +For detailed channel setup instructions, see [Chat Apps Configuration](docs/chat-apps.md). -> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access. +## 🔧 Tools -**3. Run** +### 🔍 Web Search -```bash -picoclaw gateway -``` -
+PicoClaw can search the web to provide up-to-date information. Configure in `tools.web`: -
-Matrix +| Search Engine | API Key | Free Tier | Link | +|--------------|---------|-----------|------| +| DuckDuckGo | Not needed | Unlimited | Built-in fallback | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Required | 1000 queries/day | AI-powered, China-optimized | +| [Tavily](https://tavily.com) | Required | 1000 queries/month | Optimized for AI Agents | +| [Brave Search](https://brave.com/search/api) | Required | 2000 queries/month | Fast and private | +| [Perplexity](https://www.perplexity.ai) | Required | Paid | AI-powered search | +| [SearXNG](https://github.com/searxng/searxng) | Not needed | Self-hosted | Free metasearch engine | +| [GLM Search](https://open.bigmodel.cn/) | Required | Varies | Zhipu web search | -**1. Prepare bot account** +### ⚙️ Other Tools -* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted) -* Create a bot user and obtain its access token +PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/tools_configuration.md) for details. -**2. Configure** +## 🎯 Skills -```json -{ - "channels": { - "matrix": { - "enabled": true, - "homeserver": "https://matrix.org", - "user_id": "@your-bot:matrix.org", - "access_token": "YOUR_MATRIX_ACCESS_TOKEN", - "allow_from": [] - } - } -} -``` +Skills are modular capabilities that extend your Agent. They are loaded from `SKILL.md` files in your workspace. -**3. Run** +**Install skills from ClawHub:** ```bash -picoclaw gateway +picoclaw skills search "web scraping" +picoclaw skills install ``` -For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](docs/channels/matrix/README.md). - -
- -
-LINE - -**1. Create a LINE Official Account** - -- Go to [LINE Developers Console](https://developers.line.biz/) -- Create a provider → Create a Messaging API channel -- Copy **Channel Secret** and **Channel Access Token** - -**2. Configure** +**Configure ClawHub token** (optional, for higher rate limits): +Add to your `config.json`: ```json { - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_path": "/webhook/line", - "allow_from": [] + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } } } } ``` -> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). - -**3. Set up Webhook URL** - -LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel: - -```bash -# Example with ngrok (gateway default port is 18790) -ngrok http 18790 -``` - -Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**. - -**4. Run** - -```bash -picoclaw gateway -``` - -> In group chats, the bot responds only when @mentioned. Replies quote the original message. - -
- -
-WeCom (企业微信) - -PicoClaw supports three types of WeCom integration: - -**Option 1: WeCom Bot (Bot)** - Easier setup, supports group chats -**Option 2: WeCom App (Custom App)** - More features, proactive messaging, private chat only -**Option 3: WeCom AI Bot (AI Bot)** - Official AI Bot, streaming replies, supports group & private chat - -See [WeCom AI Bot Configuration Guide](docs/channels/wecom/wecom_aibot/README.zh.md) for detailed setup instructions. - -**Quick Setup - WeCom AI Bot:** +For more details, see [Tools Configuration - Skills](docs/tools_configuration.md#skills-tool). -**1. Create an AI Bot** +## 🔗 MCP (Model Context Protocol) -* Go to WeCom Admin Console → AI Bot -* Create a new AI Bot → Set name, avatar, etc. -* Copy **Bot ID** and **Secret** - -**2. Configure** +PicoClaw natively supports [MCP](https://modelcontextprotocol.io/) — connect any MCP server to extend your Agent's capabilities with external tools and data sources. ```json { - "channels": { - "wecom_aibot": { + "tools": { + "mcp": { "enabled": true, - "bot_id": "YOUR_BOT_ID", - "secret": "YOUR_SECRET", - "allow_from": [], - "welcome_message": "Hello! How can I help you?" + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } } } } ``` -**3. Run** - -```bash -picoclaw gateway -``` - -> **Note**: WeCom AI Bot uses streaming pull protocol — no reply timeout concerns. Long tasks (>30 seconds) automatically switch to `response_url` push delivery. - -
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/tools_configuration.md#mcp-tool). ## ClawdChat Join the Agent Social Network -Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App. +Connect PicoClaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App. **Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)** -## ⚙️ Configuration - -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` | +## 🖥️ CLI Reference -**Examples:** +| Command | Description | +| ------------------------- | -------------------------------- | +| `picoclaw onboard` | Initialize config & workspace | +| `picoclaw onboard weixin` | Connect WeChat account via QR | +| `picoclaw agent -m "..."` | Chat with the agent | +| `picoclaw agent` | Interactive chat mode | +| `picoclaw gateway` | Start the gateway | +| `picoclaw status` | Show status | +| `picoclaw version` | Show version info | +| `picoclaw model` | View or switch the default model | +| `picoclaw cron list` | List all scheduled jobs | +| `picoclaw cron add ...` | Add a scheduled job | +| `picoclaw cron disable` | Disable a scheduled job | +| `picoclaw cron remove` | Remove a scheduled job | +| `picoclaw skills list` | List installed skills | +| `picoclaw skills install` | Install a skill | +| `picoclaw migrate` | Migrate data from older versions | +| `picoclaw auth login` | Authenticate with providers | -```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 +### ⏰ Scheduled Tasks / Reminders -# 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 +PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool: -# Use both for a fully customized setup -PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway -``` +* **One-time reminders**: "Remind me in 10 minutes" -> triggers once after 10min +* **Recurring tasks**: "Remind me every 2 hours" -> triggers every 2 hours +* **Cron expressions**: "Remind me at 9am daily" -> uses cron expression -### Workspace Layout - -PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`): - -``` -~/.picoclaw/workspace/ -├── sessions/ # Conversation sessions and history -├── memory/ # Long-term memory (MEMORY.md) -├── state/ # Persistent state (last channel, etc.) -├── cron/ # Scheduled jobs database -├── skills/ # Workspace-specific skills -├── AGENT.md # Structured agent definition and system prompt -├── SOUL.md # Agent soul -├── USER.md # User profile and preferences for this workspace -├── HEARTBEAT.md # Periodic task prompts (checked every 30 min) -└── ... -``` - -### Skill Sources - -By default, skills are loaded from: - -1. `~/.picoclaw/workspace/skills` (workspace) -2. `~/.picoclaw/skills` (global) -3. `/skills` (builtin) - -For advanced/test setups, you can override the builtin skills root with: - -```bash -export PICOCLAW_BUILTIN_SKILLS=/path/to/skills -``` - -### Unified Command Execution Policy - -- Generic slash commands are executed through a single path in `pkg/agent/loop.go` via `commands.Executor`. -- Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup. -- Unknown slash command (for example `/foo`) passes through to normal LLM processing. -- Registered but unsupported command on the current channel (for example `/show` on WhatsApp) returns an explicit user-facing error and stops further processing. -### 🔒 Security Sandbox - -PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace. - -#### Default Configuration - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Option | Default | Description | -| ----------------------- | ----------------------- | ----------------------------------------- | -| `workspace` | `~/.picoclaw/workspace` | Working directory for the agent | -| `restrict_to_workspace` | `true` | Restrict file/command access to workspace | - -#### Protected Tools - -When `restrict_to_workspace: true`, the following tools are sandboxed: - -| Tool | Function | Restriction | -| ------------- | ---------------- | -------------------------------------- | -| `read_file` | Read files | Only files within workspace | -| `write_file` | Write files | Only files within workspace | -| `list_dir` | List directories | Only directories within workspace | -| `edit_file` | Edit files | Only files within workspace | -| `append_file` | Append to files | Only files within workspace | -| `exec` | Execute commands | Command paths must be within workspace | - -#### Additional Exec Protection - -Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands: - -* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion -* `format`, `mkfs`, `diskpart` — Disk formatting -* `dd if=` — Disk imaging -* Writing to `/dev/sd[a-z]` — Direct disk writes -* `shutdown`, `reboot`, `poweroff` — System shutdown -* Fork bomb `:(){ :|:& };:` - -#### Error Examples - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (path outside working dir)} -``` - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)} -``` - -#### Disabling Restrictions (Security Risk) - -If you need the agent to access paths outside the workspace: - -**Method 1: Config file** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Method 2: Environment variable** - -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only. - -#### Security Boundary Consistency - -The `restrict_to_workspace` setting applies consistently across all execution paths: - -| Execution Path | Security Boundary | -| ---------------- | ---------------------------- | -| Main Agent | `restrict_to_workspace` ✅ | -| Subagent / Spawn | Inherits same restriction ✅ | -| Heartbeat tasks | Inherits same restriction ✅ | - -All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks. - -### Heartbeat (Periodic Tasks) - -PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace: - -```markdown -# Periodic Tasks - -- Check my email for important messages -- Review my calendar for upcoming events -- Check the weather forecast -``` - -The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools. - -#### Async Tasks with Spawn - -For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**: - -```markdown -# Periodic Tasks - -## Quick Tasks (respond directly) - -- Report current time - -## Long Tasks (use spawn for async) - -- Search the web for AI news and summarize -- Check email and report important messages -``` - -**Key behaviors:** - -| Feature | Description | -| ----------------------- | --------------------------------------------------------- | -| **spawn** | Creates async subagent, doesn't block heartbeat | -| **Independent context** | Subagent has its own context, no session history | -| **message tool** | Subagent communicates with user directly via message tool | -| **Non-blocking** | After spawning, heartbeat continues to next task | - -#### How Subagent Communication Works - -``` -Heartbeat triggers - ↓ -Agent reads HEARTBEAT.md - ↓ -For long task: spawn subagent - ↓ ↓ -Continue to next task Subagent works independently - ↓ ↓ -All tasks done Subagent uses "message" tool - ↓ ↓ -Respond HEARTBEAT_OK User receives result directly -``` - -The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent. - -**Configuration:** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| Option | Default | Description | -| ---------- | ------- | ---------------------------------- | -| `enabled` | `true` | Enable/disable heartbeat | -| `interval` | `30` | Check interval in minutes (min: 5) | - -**Environment variables:** - -* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable -* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval - -### Providers - -> [!NOTE] -> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level. - -| Provider | Purpose | Get API Key | -| ------------ | --------------------------------------- | ------------------------------------------------------------ | -| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) | -| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | -| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | -| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | -| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) | -| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) | - -### Model Configuration (model_list) - -> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!** - -This design also enables **multi-agent support** with flexible provider selection: - -- **Different agents, different providers**: Each agent can use its own LLM provider -- **Model fallbacks**: Configure primary and fallback models for resilience -- **Load balancing**: Distribute requests across multiple endpoints -- **Centralized configuration**: Manage all providers in one place - -#### 📋 All Supported Vendors - -| Vendor | `model` Prefix | Default API Base | Protocol | API Key | -| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- | -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) | -| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) | -| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) | -| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) | -| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | -| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) | -| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) | -| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) | -| **ModelScope (魔搭)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) | -| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### Basic Configuration - -```json -{ - "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_key": "sk-your-api-key" - }, - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_key": "sk-your-openai-key" - }, - { - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "api_key": "sk-ant-your-key" - }, - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-zhipu-key" - } - ], - "agents": { - "defaults": { - "model": "gpt-5.4" - } - } -} -``` - -#### Vendor-Specific Examples - -**OpenAI** - -```json -{ - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_key": "sk-..." -} -``` - -**VolcEngine (Doubao)** - -```json -{ - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_key": "sk-..." -} -``` - -**智谱 AI (GLM)** - -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**DeepSeek** - -```json -{ - "model_name": "deepseek-chat", - "model": "deepseek/deepseek-chat", - "api_key": "sk-..." -} -``` - -**Anthropic (with API key)** - -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "api_key": "sk-ant-your-key" -} -``` - -> Run `picoclaw auth login --provider anthropic` to paste your API token. - -**Anthropic Messages API (native format)** - -For direct Anthropic API access or custom endpoints that only support Anthropic's native message format: - -```json -{ - "model_name": "claude-opus-4-6", - "model": "anthropic-messages/claude-opus-4-6", - "api_key": "sk-ant-your-key", - "api_base": "https://api.anthropic.com" -} -``` - -> Use `anthropic-messages` protocol when: -> - Using third-party proxies that only support Anthropic's native `/v1/messages` endpoint (not OpenAI-compatible `/v1/chat/completions`) -> - Connecting to services like MiniMax, Synthetic that require Anthropic's native message format -> - The existing `anthropic` protocol returns 404 errors (indicating the endpoint doesn't support OpenAI-compatible format) -> -> **Note:** The `anthropic` protocol uses OpenAI-compatible format (`/v1/chat/completions`), while `anthropic-messages` uses Anthropic's native format (`/v1/messages`). Choose based on your endpoint's supported format. - -**Ollama (local)** - -```json -{ - "model_name": "llama3", - "model": "ollama/llama3" -} -``` - -**Custom Proxy/API** - -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -**LiteLLM Proxy** - -```json -{ - "model_name": "lite-gpt4", - "model": "litellm/lite-gpt4", - "api_base": "http://localhost:4000/v1", - "api_key": "sk-..." -} -``` - -PicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`. - -#### Load Balancing - -Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them: - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### Migration from Legacy `providers` Config - -The old `providers` configuration is **deprecated** but still supported for backward compatibility. - -**Old Config (deprecated):** - -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**New Config (recommended):** - -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -For detailed migration guide, see [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). - -### Provider Architecture - -PicoClaw routes providers by protocol family: - -- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints. -- Anthropic protocol: Claude-native API behavior. -- Codex/OAuth path: OpenAI OAuth/token authentication route. - -This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`). - -
-Zhipu - -**1. Get API key and base URL** - -* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Configure** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Your API Key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - } -} -``` - -**3. Run** - -```bash -picoclaw agent -m "Hello" -``` - -
- -
-Full config example - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "session": { - "dm_scope": "per-channel-peer", - "backlog_limit": 20 - }, - "providers": { - "openrouter": { - "api_key": "sk-or-v1-xxx" - }, - "groq": { - "api_key": "gsk_xxx" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "123456:ABC...", - "allow_from": ["123456789"] - }, - "discord": { - "enabled": true, - "token": "", - "allow_from": [""] - }, - "whatsapp": { - "enabled": false, - "bridge_url": "ws://localhost:3001", - "use_native": false, - "session_store_path": "", - "allow_from": [] - }, - "feishu": { - "enabled": false, - "app_id": "cli_xxx", - "app_secret": "xxx", - "encrypt_key": "", - "verification_token": "", - "allow_from": [] - }, - "qq": { - "enabled": false, - "app_id": "", - "app_secret": "", - "allow_from": [] - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "BSA...", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - }, - "perplexity": { - "enabled": false, - "api_key": "", - "max_results": 5 - }, - "searxng": { - "enabled": false, - "base_url": "http://localhost:8888", - "max_results": 5 - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -## 🖥️ CLI Reference - -| Command | Description | -| ------------------------- | ----------------------------- | -| `picoclaw onboard` | Initialize config & workspace | -| `picoclaw onboard weixin` | Connect WeChat account via QR | -| `picoclaw agent -m "..."` | Chat with the agent | -| `picoclaw agent` | Interactive chat mode | -| `picoclaw gateway` | Start the gateway | -| `picoclaw status` | Show status | -| `picoclaw version` | Show version info | -| `picoclaw model` | Show or change default model | -| `picoclaw cron list` | List all scheduled jobs | -| `picoclaw cron add ...` | Add a scheduled job | -| `picoclaw cron disable` | Disable a scheduled job | -| `picoclaw cron remove` | Remove a scheduled job | -| `picoclaw skills list` | List installed skills | -| `picoclaw skills install` | Install a skill | -| `picoclaw migrate` | Migrate data from older versions | -| `picoclaw auth login` | Authenticate with providers | - -### Scheduled Tasks / Reminders - -PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool: +## 📚 Documentation -* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min -* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours -* **Cron expressions**: "Remind me at 9am daily" → uses cron expression +For detailed guides beyond this README: + +| Topic | Description | +|-------|-------------| +| [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes | +| [Chat Apps](docs/chat-apps.md) | All 17+ channel setup guides | +| [Configuration](docs/configuration.md) | Environment variables, workspace layout, security sandbox | +| [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration | +| [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration | +| [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks | +| [Steering](docs/steering.md) | Inject messages into a running agent loop between tool calls | +| [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle | +| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions | +| [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills | +| [Hardware Compatibility](docs/hardware-compatibility.md) | Tested boards, minimum requirements | ## 🤝 Contribute & Roadmap -PRs welcome! The codebase is intentionally small and readable. 🤗 +PRs welcome! The codebase is intentionally small and readable. -See our full [Community Roadmap](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md). +See our [Community Roadmap](https://github.com/sipeed/picoclaw/issues/988) and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Developer group building, join after your first merged PR! User Groups: -discord: +Discord: WeChat: WeChat group QR code diff --git a/README.pt-br.md b/README.pt-br.md index c1df570a58..3c039f1906 100644 --- a/README.pt-br.md +++ b/README.pt-br.md @@ -1,9 +1,9 @@
- PicoClaw +PicoClaw -

PicoClaw: Assistente de IA Ultra-Eficiente em Go

+

PicoClaw: Assistente de IA Ultra-Eficiente em Go

-

Hardware de $10 · <10MB de RAM · Boot em <1s · 皮皮虾,我们走!

+

Hardware de $10 · 10MB de RAM · Boot em ms · Let's Go, PicoClaw!

Go Hardware @@ -24,149 +24,137 @@ --- -> **PicoClaw** é um projeto open-source independente iniciado pela [Sipeed](https://sipeed.com). É escrito inteiramente em **Go** — não é um fork do OpenClaw, NanoBot ou qualquer outro projeto. +> **PicoClaw** é um projeto open-source independente iniciado pela [Sipeed](https://sipeed.com), escrito inteiramente em **Go** do zero — não é um fork do OpenClaw, NanoBot ou qualquer outro projeto. -🦐 PicoClaw é um assistente pessoal de IA ultra-leve inspirado no [NanoBot](https://github.com/HKUDS/nanobot), reescrito do zero em Go por meio de um processo de auto-inicialização (self-bootstrapping), onde o próprio agente de IA conduziu toda a migração de arquitetura e otimização de código. +**PicoClaw** é um assistente de IA pessoal ultra-leve inspirado no [NanoBot](https://github.com/HKUDS/nanobot). Foi reconstruído do zero em **Go** por meio de um processo de "auto-bootstrapping" — o próprio AI Agent conduziu a migração de arquitetura e a otimização do código. -⚡️ Roda em hardware de $10 com <10MB de RAM: Isso é 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini! +**Roda em hardware de $10 com menos de 10MB de RAM** — isso é 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 DECLARAÇÃO DE SEGURANÇA & CANAIS OFICIAIS** +> **Aviso de Segurança** > -> * **SEM CRIPTOMOEDAS:** O PicoClaw **NÃO** possui nenhum token/moeda oficial. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **GOLPES**. -> -> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é o **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é o **[sipeed.com](https://sipeed.com)** -> * **Aviso:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros. -> * **Aviso:** O PicoClaw está em fase inicial de desenvolvimento e pode ter problemas de segurança de rede não resolvidos. Não implante em ambientes de produção antes da versão v1.0. -> * **Nota:** O PicoClaw recentemente fez merge de muitos PRs, o que pode resultar em maior consumo de memória (10–20MB) nas versões mais recentes. Planejamos priorizar a otimização de recursos assim que o conjunto de funcionalidades estiver estável. +> * **SEM CRIPTO:** O PicoClaw **não** emitiu nenhum token oficial ou criptomoeda. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **golpes**. +> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é **[sipeed.com](https://sipeed.com)** +> * **ATENÇÃO:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros. Não confie neles. +> * **NOTA:** O PicoClaw está em desenvolvimento rápido inicial. Podem existir problemas de segurança não resolvidos. Não implante em produção antes da v1.0. +> * **NOTA:** O PicoClaw mesclou muitos PRs recentemente. Builds recentes podem usar 10-20MB de RAM. A otimização de recursos está planejada após a estabilização de funcionalidades. ## 📢 Novidades -2026-03-17 🚀 **v0.2.3 Lançado!** Interface de bandeja do sistema (Windows & Linux), rastreamento de status de sub-agentes (`spawn_status`), hot-reload experimental do gateway, portões de segurança para cron e 2 correções de segurança. PicoClaw agora com **25K ⭐**! +2026-03-17 🚀 **v0.2.3 Lançada!** UI na bandeja do sistema (Windows e Linux), consulta de status de sub-agent (`spawn_status`), hot-reload experimental do Gateway, controle de segurança do Cron e 2 correções de segurança. O PicoClaw atingiu **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos canais (Matrix/IRC/WeCom/Discord Proxy), 3 novos provedores (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL e roteamento de modelos. +2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos channels (Matrix/IRC/WeCom/Discord Proxy), 3 novos providers (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL, roteamento de modelos. -2026-02-28 📦 **v0.2.0** lançado com suporte a Docker Compose e launcher Web UI. +2026-02-28 📦 **v0.2.0** lançada com suporte a Docker Compose e Web UI Launcher. -2026-02-26 🎉 PicoClaw atingiu **20K stars** em apenas 17 dias! Orquestração automática de canais e interfaces de capacidade implementadas. +2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis.

-Novidades anteriores... +Notícias anteriores... -2026-02-16 🎉 PicoClaw atingiu 12K stars em uma semana! Papéis de maintainers da comunidade e [roadmap](ROADMAP.md) publicados oficialmente. +2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](ROADMAP.md) lançados oficialmente. -2026-02-13 🎉 PicoClaw atingiu 5000 stars em 4 dias! Roadmap do Projeto e Grupo de Desenvolvedores em preparação. +2026-02-13 🎉 O PicoClaw ultrapassa 5000 Stars em 4 dias! Roadmap do projeto e grupos de desenvolvedores em andamento. -2026-02-09 🎉 **PicoClaw Lançado!** Construído em 1 dia para trazer Agentes de IA para hardware de $10 com <10MB de RAM. 🦐 PicoClaw, Partiu! +2026-02-09 🎉 **PicoClaw Lançado!** Construído em 1 dia para levar AI Agents a hardware de $10 com menos de 10MB de RAM. Let's Go, PicoClaw!
## ✨ Funcionalidades -🪶 **Ultra-Leve**: Consumo de memória <10MB — 99% menor que o OpenClaw para funcionalidades essenciais.* +🪶 **Ultra-leve**: Footprint de memória do núcleo <10MB — 99% menor que o OpenClaw.* + +💰 **Custo mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini. -💰 **Custo Mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini. +⚡️ **Boot ultrarrápido**: Inicialização 400x mais rápida. Boot em menos de 1s mesmo em um processador single-core de 0,6GHz. -⚡️ **Inicialização Relâmpago**: Tempo de inicialização 400X mais rápido, boot em <1 segundo mesmo em CPU single-core de 0.6GHz. +🌍 **Verdadeiramente portátil**: Binário único para arquiteturas RISC-V, ARM, MIPS e x86. Um binário, roda em qualquer lugar! -🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM, MIPS e x86. Um clique e já era! +🤖 **Bootstrapped por IA**: Implementação nativa pura em Go — 95% do código principal foi gerado por um Agent e refinado por revisão humana. -🤖 **Auto-Construído por IA**: Implementação nativa em Go de forma autônoma — 95% do núcleo gerado pelo Agente com refinamento humano no loop. +🔌 **Suporte a MCP**: Integração nativa com o [Model Context Protocol](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do Agent. -🔌 **Suporte MCP**: Integração nativa com o [Model Context Protocol](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do agente. +👁️ **Pipeline de visão**: Envie imagens e arquivos diretamente ao Agent — codificação base64 automática para LLMs multimodais. -👁️ **Pipeline de Visão**: Envie imagens e arquivos diretamente ao agente — codificação base64 automática para LLMs multimodais. +🧠 **Roteamento inteligente**: Roteamento de modelos baseado em regras — consultas simples vão para modelos leves, economizando custos de API. -🧠 **Roteamento Inteligente**: Roteamento de modelos baseado em regras — consultas simples vão para modelos leves, economizando custos de API. +_*Builds recentes podem usar 10-20MB devido a merges rápidos de PRs. Otimização de recursos está planejada. Comparação de velocidade de boot baseada em benchmarks de single-core a 0,8GHz (veja tabela abaixo)._ -_*Versões recentes podem usar 10–20MB devido a merges rápidos de funcionalidades. Otimização de recursos está planejada. Comparação de inicialização baseada em benchmarks de single-core a 0.8GHz (veja tabela abaixo)._ +
-| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Linguagem** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **Inicialização**
(CPU 0.8GHz) | >500s | >30s | **<1s** | -| **Custo** | Mac Mini $599 | Maioria dos SBC Linux
~$50 | **Qualquer placa Linux**
**A partir de $10** | +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Linguagem** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Tempo de boot**
(core 0,8GHz) | >500s | >30s | **<1s** | +| **Custo** | Mac Mini $599 | Maioria das placas Linux ~$50 | **Qualquer placa Linux**
**a partir de $10** | PicoClaw -> 📋 **[Lista de Compatibilidade de Hardware](docs/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 a Raspberry Pi e telefones Android. Sua placa não está listada? Envie um PR! +
+ +> **[Lista de Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR! + +

+PicoClaw Hardware Compatibility +

## 🦾 Demonstração ### 🛠️ Fluxos de Trabalho Padrão do Assistente - - - - - - - - - - - - - - - + + + + + + + + + + + + + + +

🧩 Engenharia Full-Stack

🗂️ Gerenciamento de Logs & Planejamento

🔎 Busca Web & Aprendizado

Desenvolver • Implantar • EscalarAgendar • Automatizar • MemorizarDescobrir • Analisar • Tendências

Modo Engenheiro Full-Stack

Registro e Planejamento

Busca na Web e Aprendizado

Desenvolver · Implantar · EscalarAgendar · Automatizar · LembrarDescobrir · Insights · Tendências
-### 📱 Rode em celulares Android antigos - -Dê uma segunda vida ao seu celular de dez anos atrás! Transforme-o em um assistente de IA inteligente com o PicoClaw. Início rápido: - -1. **Instale o [Termux](https://github.com/termux/termux-app)** (Baixe em [GitHub Releases](https://github.com/termux/termux-app/releases), ou busque no F-Droid / Google Play). -2. **Execute os comandos** - -```bash -# Baixe a versão mais recente em https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot fornece um layout padrão do sistema de arquivos Linux -``` - -Depois siga as instruções na seção "Início Rápido" para completar a configuração! - -PicoClaw - -### 🐜 Implantação Inovadora com Baixo Consumo +### 🐜 Implantação Inovadora de Baixo Consumo O PicoClaw pode ser implantado em praticamente qualquer dispositivo Linux! -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versão E(Ethernet) ou W(WiFi6), para Assistente Doméstico Minimalista -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) para Manutenção Automatizada de Servidores -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) para Monitoramento Inteligente +- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) edição E(Ethernet) ou W(WiFi6), para um assistente doméstico mínimo +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), para operações automatizadas de servidor +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), para vigilância inteligente -🌟 Mais cenários de implantação aguardam você! +🌟 Mais Casos de Implantação Aguardam! ## 📦 Instalação -### Baixar de picoclaw.io (Recomendado) +### Download pelo picoclaw.io (Recomendado) -Visite **[picoclaw.io](https://picoclaw.io)** — o site oficial detecta automaticamente sua plataforma e oferece download com um clique. Sem necessidade de escolher manualmente a arquitetura. +Acesse **[picoclaw.io](https://picoclaw.io)** — o site oficial detecta automaticamente sua plataforma e fornece download com um clique. Não é necessário selecionar a arquitetura manualmente. -### Baixar binário pré-compilado +### Download do binário pré-compilado Alternativamente, baixe o binário para sua plataforma na página de [GitHub Releases](https://github.com/sipeed/picoclaw/releases). @@ -178,80 +166,413 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Build, sem necessidade de instalar +# Compilar o binário principal make build -# Build para múltiplas plataformas +# Compilar o Web UI Launcher (necessário para o modo WebUI) +make build-launcher + +# Compilar para múltiplas plataformas make build-all -# Build para Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) +# Compilar para Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) make build-pi-zero -# Build e Instalar +# Compilar e instalar make install ``` -**Raspberry Pi Zero 2 W:** Use o binário correspondente ao seu SO: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Ou execute `make build-pi-zero` para compilar ambos. +**Raspberry Pi Zero 2 W:** Use o binário que corresponde ao seu SO: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Ou execute `make build-pi-zero` para compilar ambos. -## 📚 Documentação +## 🚀 Guia de Início Rápido -Para guias detalhados, consulte a documentação abaixo. Este README cobre apenas o início rápido. +### 🌐 WebUI Launcher (Recomendado para Desktop) -| Tópico | Descrição | -|--------|-----------| -| 🐳 [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração Docker Compose, modos Launcher/Agent, configuração de Início Rápido | -| 💬 [Apps de Chat](docs/pt-br/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom e mais | -| ⚙️ [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, estrutura do workspace, fontes de skills, sandbox de segurança, heartbeat | -| 🔌 [Provedores & Modelos](docs/pt-br/providers.md) | 20+ provedores LLM, roteamento de modelos, configuração model_list, arquitetura de provedores | -| 🔄 [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agentes | -| 🐛 [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções | -| 🔧 [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de execução | -| 📋 [Compatibilidade de Hardware](docs/hardware-compatibility.md) | Placas testadas, requisitos mínimos, como adicionar sua placa | +O WebUI Launcher fornece uma interface baseada em navegador para configuração e chat. Esta é a maneira mais fácil de começar — sem necessidade de conhecimento de linha de comando. + +**Opção 1: Duplo clique (Desktop)** + +Após baixar de [picoclaw.io](https://picoclaw.io), dê duplo clique em `picoclaw-launcher` (ou `picoclaw-launcher.exe` no Windows). Seu navegador abrirá automaticamente em `http://localhost:18800`. + +**Opção 2: Linha de comando** + +```bash +picoclaw-launcher +# Abra http://localhost:18800 no seu navegador +``` + +> [!TIP] +> **Acesso remoto / Docker / VM:** Adicione a flag `-public` para escutar em todas as interfaces: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**Primeiros passos:** + +Abra o WebUI e então: **1)** Configure um Provider (adicione sua API key de LLM) -> **2)** Configure um Channel (ex.: Telegram) -> **3)** Inicie o Gateway -> **4)** Converse! + +Para documentação detalhada do WebUI, veja [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (alternativa) + +```bash +# 1. Clone este repositório +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. Primeira execução — gera automaticamente docker/data/config.json e encerra +# (só é acionado quando config.json e workspace/ estão ausentes) +docker compose -f docker/docker-compose.yml --profile launcher up +# O container imprime "First-run setup complete." e para. + +# 3. Configure suas API keys +vim docker/data/config.json + +# 4. Iniciar +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Abra http://localhost:18800 +``` + +> **Usuários de Docker / VM:** O Gateway escuta em `127.0.0.1` por padrão. Defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` ou use a flag `-public` para torná-lo acessível pelo host. + +```bash +# Verificar logs +docker compose -f docker/docker-compose.yml logs -f + +# Parar +docker compose -f docker/docker-compose.yml --profile launcher down + +# Atualizar +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher (Recomendado para Headless / SSH) + +O TUI (Terminal UI) Launcher fornece uma interface de terminal completa para configuração e gerenciamento. Ideal para servidores, Raspberry Pi e outros ambientes headless. + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**Primeiros passos:** + +Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um Channel -> **3)** Iniciar o Gateway -> **4)** Conversar! + +Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Dê uma segunda vida ao seu celular de uma década! Transforme-o em um Assistente de IA inteligente com o PicoClaw. + +**Opção 1: Termux (disponível agora)** + +1. Instale o [Termux](https://github.com/termux/termux-app) (baixe nas [GitHub Releases](https://github.com/termux/termux-app/releases), ou pesquise no F-Droid / Google Play) +2. Execute os seguintes comandos: + +```bash +# Baixar a versão mais recente +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot fornece um layout padrão de sistema de arquivos Linux +``` + +Em seguida, siga a seção Terminal Launcher abaixo para concluir a configuração. + +PicoClaw on Termux + +**Opção 2: Instalação via APK (em breve)** + +Um APK Android independente com WebUI integrado está em desenvolvimento. Fique ligado! + +
+Terminal Launcher (para ambientes com recursos limitados) + +Para ambientes mínimos onde apenas o binário principal `picoclaw` está disponível (sem Launcher UI), você pode configurar tudo via linha de comando e um arquivo de configuração JSON. + +**1. Inicializar** + +```bash +picoclaw onboard +``` + +Isso cria `~/.picoclaw/config.json` e o diretório workspace. + +**2. Configurar** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> Veja `config/config.example.json` no repositório para um template de configuração completo com todas as opções disponíveis. + +**3. Conversar** + +```bash +# Pergunta única +picoclaw agent -m "What is 2+2?" + +# Modo interativo +picoclaw agent + +# Iniciar gateway para integração com app de chat +picoclaw gateway +``` + +
+ +## 🔌 Providers (LLM) + +O PicoClaw suporta mais de 30 providers de LLM através da configuração `model_list`. Use o formato `protocolo/modelo`: + +| Provider | Protocolo | API Key | Notas | +|----------|-----------|---------|-------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Obrigatória | GPT-5.4, GPT-4o, o3, etc. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Obrigatória | Claude Opus 4.6, Sonnet 4.6, etc. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Obrigatória | Gemini 3 Flash, 2.5 Pro, etc. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Obrigatória | 200+ modelos, API unificada | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Obrigatória | GLM-4.7, GLM-5, etc. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Obrigatória | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Obrigatória | Modelos Doubao, Ark | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Obrigatória | Qwen3, Qwen-Max, etc. | +| [Groq](https://console.groq.com/keys) | `groq/` | Obrigatória | Inferência rápida (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Obrigatória | Modelos Kimi | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Obrigatória | Modelos MiniMax | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Obrigatória | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Obrigatória | Modelos hospedados pela NVIDIA | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Obrigatória | Inferência rápida | +| [Novita AI](https://novita.ai/) | `novita/` | Obrigatória | Vários modelos abertos | +| [Ollama](https://ollama.com/) | `ollama/` | Não necessária | Modelos locais, self-hosted | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Não necessária | Implantação local, compatível com OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varia | Proxy para 100+ providers | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Obrigatória | Implantação Azure Enterprise | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login por código de dispositivo | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+Implantação local (Ollama, vLLM, etc.) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Para detalhes completos de configuração de providers, veja [Providers & Models](docs/pt-br/providers.md). + +
+ +## 💬 Channels (Apps de Chat) + +Converse com seu PicoClaw por meio de mais de 17 plataformas de mensagens: + +| Channel | Configuração | Protocolo | Docs | +|---------|--------------|-----------|------| +| **Telegram** | Fácil (bot token) | Long polling | [Guia](docs/channels/telegram/README.pt-br.md) | +| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](docs/channels/discord/README.pt-br.md) | +| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](docs/pt-br/chat-apps.md#whatsapp) | +| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](docs/pt-br/chat-apps.md#weixin) | +| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](docs/channels/qq/README.pt-br.md) | +| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](docs/channels/slack/README.pt-br.md) | +| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](docs/channels/matrix/README.pt-br.md) | +| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](docs/channels/dingtalk/README.pt-br.md) | +| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](docs/channels/feishu/README.pt-br.md) | +| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](docs/channels/line/README.pt-br.md) | +| **WeCom Bot** | Médio (webhook URL) | Webhook | [Guia](docs/channels/wecom/wecom_bot/README.pt-br.md) | +| **WeCom App** | Médio (credenciais corporativas) | Webhook | [Guia](docs/channels/wecom/wecom_app/README.pt-br.md) | +| **WeCom AI Bot** | Médio (token + chave AES) | WebSocket / Webhook | [Guia](docs/channels/wecom/wecom_aibot/README.pt-br.md) | +| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](docs/pt-br/chat-apps.md#irc) | +| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](docs/channels/onebot/README.pt-br.md) | +| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](docs/channels/maixcam/README.pt-br.md) | +| **Pico** | Fácil (habilitar) | Protocolo nativo | Integrado | +| **Pico Client** | Fácil (WebSocket URL) | WebSocket | Integrado | + +> Todos os channels baseados em webhook compartilham um único servidor HTTP do Gateway (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). O Feishu usa modo WebSocket/SDK e não utiliza o servidor HTTP compartilhado. + +Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](docs/pt-br/chat-apps.md). + +## 🔧 Ferramentas + +### 🔍 Busca na Web + +O PicoClaw pode pesquisar na web para fornecer informações atualizadas. Configure em `tools.web`: + +| Motor de Busca | API Key | Nível Gratuito | Link | +|----------------|---------|----------------|------| +| DuckDuckGo | Não necessária | Ilimitado | Fallback integrado | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Obrigatória | 1000 consultas/dia | IA, otimizado para chinês | +| [Tavily](https://tavily.com) | Obrigatória | 1000 consultas/mês | Otimizado para AI Agents | +| [Brave Search](https://brave.com/search/api) | Obrigatória | 2000 consultas/mês | Rápido e privado | +| [Perplexity](https://www.perplexity.ai) | Obrigatória | Pago | Busca com IA | +| [SearXNG](https://github.com/searxng/searxng) | Não necessária | Self-hosted | Metabuscador gratuito | +| [GLM Search](https://open.bigmodel.cn/) | Obrigatória | Varia | Busca web Zhipu | + +### ⚙️ Outras Ferramentas + +O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) para detalhes. + +## 🎯 Skills -## ClawdChat Junte-se à Rede Social de Agentes +Skills são capacidades modulares que estendem seu Agent. Elas são carregadas a partir de arquivos `SKILL.md` no seu workspace. -Conecte o PicoClaw à Rede Social de Agentes simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado. +**Instalar skills do ClawHub:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Configurar token do ClawHub** (opcional, para limites de taxa mais altos): + +Adicione ao seu `config.json`: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Para mais detalhes, veja [Configuração de Ferramentas - Skills](docs/pt-br/tools_configuration.md#skills-tool). + +## 🔗 MCP (Model Context Protocol) + +O PicoClaw suporta nativamente o [MCP](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do seu Agent com ferramentas externas e fontes de dados. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](docs/pt-br/tools_configuration.md#mcp-tool). + +## ClawdChat Junte-se à Rede Social de Agents + +Conecte o PicoClaw à Rede Social de Agents simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado. **Leia `https://clawdchat.ai/skill.md` e siga as instruções para entrar no [ClawdChat.ai](https://clawdchat.ai)** ## 🖥️ Referência CLI -| Comando | Descrição | -| ------------------------- | ----------------------------- | -| `picoclaw onboard` | Inicializar configuração & workspace | -| `picoclaw agent -m "..."` | Conversar com o agente | -| `picoclaw agent` | Modo de chat interativo | -| `picoclaw gateway` | Iniciar o gateway | -| `picoclaw status` | Mostrar status | -| `picoclaw version` | Mostrar informações de versão | -| `picoclaw cron list` | Listar todas as tarefas agendadas | -| `picoclaw cron add ...` | Adicionar uma tarefa agendada | -| `picoclaw cron disable` | Desabilitar uma tarefa agendada | -| `picoclaw cron remove` | Remover uma tarefa agendada | -| `picoclaw skills list` | Listar skills instaladas | -| `picoclaw skills install` | Instalar uma skill | -| `picoclaw migrate` | Migrar dados de versões anteriores | -| `picoclaw auth login` | Autenticar com provedores | -| `picoclaw model` | Ver ou trocar o modelo padrão | - -### Tarefas Agendadas / Lembretes - -O PicoClaw suporta lembretes agendados e tarefas recorrentes por meio da ferramenta `cron`: - -* **Lembretes únicos**: "Me lembre em 10 minutos" → dispara uma vez após 10min -* **Tarefas recorrentes**: "Me lembre a cada 2 horas" → dispara a cada 2 horas -* **Expressões Cron**: "Me lembre às 9h todos os dias" → usa expressão cron +| Comando | Descrição | +| ------------------------- | -------------------------------------- | +| `picoclaw onboard` | Inicializar config e workspace | +| `picoclaw onboard weixin` | Conectar conta WeChat via QR | +| `picoclaw agent -m "..."` | Conversar com o agent | +| `picoclaw agent` | Modo de chat interativo | +| `picoclaw gateway` | Iniciar o gateway | +| `picoclaw status` | Exibir status | +| `picoclaw version` | Exibir informações de versão | +| `picoclaw model` | Ver ou trocar o modelo padrão | +| `picoclaw cron list` | Listar todos os jobs agendados | +| `picoclaw cron add ...` | Adicionar um job agendado | +| `picoclaw cron disable` | Desabilitar um job agendado | +| `picoclaw cron remove` | Remover um job agendado | +| `picoclaw skills list` | Listar skills instaladas | +| `picoclaw skills install` | Instalar uma skill | +| `picoclaw migrate` | Migrar dados de versões anteriores | +| `picoclaw auth login` | Autenticar com providers | + +### ⏰ Tarefas Agendadas / Lembretes + +O PicoClaw suporta lembretes agendados e tarefas recorrentes através da ferramenta `cron`: + +* **Lembretes únicos**: "Lembre-me em 10 minutos" -> dispara uma vez após 10min +* **Tarefas recorrentes**: "Lembre-me a cada 2 horas" -> dispara a cada 2 horas +* **Expressões cron**: "Lembre-me às 9h diariamente" -> usa expressão cron + +## 📚 Documentação + +Para guias detalhados além deste README: + +| Tópico | Descrição | +|--------|-----------| +| [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração do Docker Compose, modos Launcher/Agent | +| [Apps de Chat](docs/pt-br/chat-apps.md) | Guias de configuração para todos os 17+ channels | +| [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança | +| [Providers & Models](docs/pt-br/providers.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list | +| [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents | +| [Hooks](docs/hooks/README.md) | Sistema de hooks orientado a eventos: observadores, interceptores, hooks de aprovação | +| [Steering](docs/steering.md) | Injetar mensagens em um loop de agente em execução | +| [SubTurn](docs/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida | +| [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções | +| [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills | +| [Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md) | Placas testadas, requisitos mínimos | ## 🤝 Contribuir & Roadmap -PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível. 🤗 +PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível. -Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) completo. +Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes. -Grupo de desenvolvedores em formação. Junte-se após seu primeiro PR com merge! +Grupo de desenvolvedores em formação, entre após seu primeiro PR mesclado! -Grupos de usuários: +Grupos de Usuários: -discord: +Discord: -PicoClaw +WeChat: +WeChat group QR code diff --git a/README.vi.md b/README.vi.md index cd65ac5263..b63fd4ef7c 100644 --- a/README.vi.md +++ b/README.vi.md @@ -1,9 +1,9 @@
- PicoClaw +PicoClaw -

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

+

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

-

Phần cứng $10 · <10MB RAM · Khởi động <1 giây · Nào, xuất phát!

+

Phần cứng $10 · RAM 10MB · Khởi động ms · Let's Go, PicoClaw!

Go Hardware @@ -24,153 +24,141 @@ --- -> **PicoClaw** là dự án mã nguồn mở độc lập được khởi xướng bởi [Sipeed](https://sipeed.com). Được viết hoàn toàn bằng **Go** — không phải là bản fork của OpenClaw, NanoBot hay bất kỳ dự án nào khác. +> **PicoClaw** là một dự án mã nguồn mở độc lập do [Sipeed](https://sipeed.com) khởi xướng, được viết hoàn toàn bằng **Go** từ đầu — không phải fork của OpenClaw, NanoBot hay bất kỳ dự án nào khác. -🦐 PicoClaw là trợ lý AI cá nhân siêu nhẹ, lấy cảm hứng từ [NanoBot](https://github.com/HKUDS/nanobot), được viết lại hoàn toàn bằng Go thông qua quá trình "tự khởi tạo" (self-bootstrapping) — nơi chính AI Agent đã tự dẫn dắt toàn bộ quá trình chuyển đổi kiến trúc và tối ưu hóa mã nguồn. +**PicoClaw** là trợ lý AI cá nhân siêu nhẹ lấy cảm hứng từ [NanoBot](https://github.com/HKUDS/nanobot). Nó được xây dựng lại từ đầu bằng **Go** thông qua quá trình "tự khởi động" — chính AI Agent đã dẫn dắt quá trình di chuyển kiến trúc và tối ưu hóa mã nguồn. -⚡️ Chạy trên phần cứng chỉ $10 với RAM <10MB: Tiết kiệm 99% bộ nhớ so với OpenClaw và rẻ hơn 98% so với Mac mini! +**Chạy trên phần cứng $10 với <10MB RAM** — ít hơn 99% bộ nhớ so với OpenClaw và rẻ hơn 98% so với Mac mini! - - - - + + + +
-

- -

-
-

- -

-
+

+ +

+
+

+ +

+
> [!CAUTION] -> **🚨 TUYÊN BỐ BẢO MẬT & KÊNH CHÍNH THỨC** +> **Thông báo Bảo mật** > -> * **KHÔNG CÓ CRYPTO:** PicoClaw **KHÔNG** có bất kỳ token/coin chính thức nào. Mọi thông tin trên `pump.fun` hoặc các sàn giao dịch khác đều là **LỪA ĐẢO**. -> -> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, website công ty là **[sipeed.com](https://sipeed.com)** -> * **Cảnh báo:** Nhiều tên miền `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký. -> * **Cảnh báo:** PicoClaw đang trong giai đoạn phát triển sớm và có thể còn các vấn đề bảo mật mạng chưa được giải quyết. Không nên triển khai lên môi trường production trước phiên bản v1.0. -> * **Lưu ý:** PicoClaw gần đây đã merge nhiều PR, dẫn đến bộ nhớ sử dụng có thể lớn hơn (10–20MB) ở các phiên bản mới nhất. Chúng tôi sẽ ưu tiên tối ưu tài nguyên khi bộ tính năng đã ổn định. +> * **KHÔNG CÓ CRYPTO:** PicoClaw **chưa** phát hành bất kỳ token hay tiền điện tử chính thức nào. Mọi thông tin trên `pump.fun` hoặc các nền tảng giao dịch khác đều là **lừa đảo**. +> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, và website công ty là **[sipeed.com](https://sipeed.com)** +> * **CẢNH BÁO:** Nhiều domain `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký. Đừng tin tưởng chúng. +> * **LƯU Ý:** PicoClaw đang trong giai đoạn phát triển nhanh. Có thể còn các vấn đề bảo mật chưa được giải quyết. Không triển khai lên môi trường production trước v1.0. +> * **LƯU Ý:** PicoClaw gần đây đã merge nhiều PR. Các bản build gần đây có thể dùng 10-20MB RAM. Tối ưu hóa tài nguyên được lên kế hoạch sau khi tính năng ổn định. ## 📢 Tin tức -2026-03-17 🚀 **v0.2.3 Phát hành!** Giao diện khay hệ thống (Windows & Linux), theo dõi trạng thái sub-agent (`spawn_status`), hot-reload gateway thử nghiệm, cổng bảo mật cron và 2 bản vá bảo mật. PicoClaw đạt **25K ⭐**! +2026-03-17 🚀 **v0.2.3 đã phát hành!** Giao diện system tray (Windows & Linux), truy vấn trạng thái sub-agent (`spawn_status`), thử nghiệm Gateway hot-reload, bảo mật Cron, và 2 bản vá bảo mật. PicoClaw đã đạt **25K Stars**! -2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất!** Hỗ trợ giao thức MCP, 4 kênh mới (Matrix/IRC/WeCom/Discord Proxy), 3 nhà cung cấp mới (Kimi/Minimax/Avian), pipeline xử lý hình ảnh, bộ nhớ JSONL và định tuyến mô hình. +2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất từ trước đến nay!** Hỗ trợ giao thức MCP, 4 Channel mới (Matrix/IRC/WeCom/Discord Proxy), 3 Provider mới (Kimi/Minimax/Avian), pipeline thị giác, bộ nhớ JSONL, định tuyến mô hình. -2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và launcher Web UI. +2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và Web UI Launcher. -2026-02-26 🎉 PicoClaw đạt **20K stars** chỉ trong 17 ngày! Tự động điều phối kênh và giao diện năng lực đã được triển khai. +2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động.

-Tin tức cũ hơn... +Tin tức trước đó... -2026-02-16 🎉 PicoClaw đạt 12K stars chỉ trong một tuần! Vai trò maintainer cộng đồng và [roadmap](ROADMAP.md) đã được công bố chính thức. +2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](ROADMAP.md) chính thức ra mắt. -2026-02-13 🎉 PicoClaw đạt 5000 stars trong 4 ngày! Lộ trình dự án và Nhóm phát triển đang được thiết lập. +2026-02-13 🎉 PicoClaw vượt 5000 Stars trong 4 ngày! Lộ trình dự án và nhóm nhà phát triển đang được xây dựng. -2026-02-09 🎉 **PicoClaw chính thức ra mắt!** Được xây dựng trong 1 ngày để mang AI Agent đến phần cứng $10 với RAM <10MB. 🦐 PicoClaw, Lên Đường! +2026-02-09 🎉 **PicoClaw ra mắt!** Được xây dựng trong 1 ngày để đưa AI Agent lên phần cứng $10 với <10MB RAM. Let's Go, PicoClaw!
-## ✨ Tính năng nổi bật +## ✨ Tính năng -🪶 **Siêu nhẹ**: Bộ nhớ sử dụng <10MB — nhỏ hơn 99% so với OpenClaw (chức năng cốt lõi).* +🪶 **Siêu nhẹ**: Bộ nhớ lõi <10MB — nhỏ hơn 99% so với OpenClaw.* 💰 **Chi phí tối thiểu**: Đủ hiệu quả để chạy trên phần cứng $10 — rẻ hơn 98% so với Mac mini. -⚡️ **Khởi động siêu nhanh**: Nhanh gấp 400 lần, khởi động trong <1 giây ngay cả trên CPU đơn nhân 0.6GHz. - -🌍 **Di động thực sự**: Một file binary duy nhất chạy trên RISC-V, ARM, MIPS và x86. Một click là chạy! - -🤖 **AI tự xây dựng**: Triển khai Go-native tự động — 95% mã nguồn cốt lõi được Agent tạo ra, với sự tinh chỉnh của con người. - -🔌 **Hỗ trợ MCP**: Tích hợp [Model Context Protocol](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ máy chủ MCP nào để mở rộng khả năng của agent. +⚡️ **Khởi động cực nhanh**: Khởi động nhanh hơn 400 lần. Khởi động trong <1 giây ngay cả trên bộ xử lý đơn nhân 0.6GHz. -👁️ **Pipeline Xử lý Hình ảnh**: Gửi hình ảnh và tệp trực tiếp cho agent — tự động mã hóa base64 cho các LLM đa phương thức. +🌍 **Thực sự di động**: Một binary duy nhất cho các kiến trúc RISC-V, ARM, MIPS và x86. Một binary, chạy mọi nơi! -🧠 **Định tuyến Thông minh**: Định tuyến mô hình dựa trên quy tắc — truy vấn đơn giản chuyển đến mô hình nhẹ, tiết kiệm chi phí API. +🤖 **Được AI khởi động**: Triển khai Go thuần túy — 95% mã lõi được tạo bởi Agent và tinh chỉnh qua quy trình human-in-the-loop. -_*Các phiên bản gần đây có thể sử dụng 10–20MB do merge tính năng nhanh chóng. Tối ưu tài nguyên đang được lên kế hoạch. So sánh thời gian khởi động dựa trên benchmark đơn nhân 0.8GHz (xem bảng bên dưới)._ +🔌 **Hỗ trợ MCP**: Tích hợp [Model Context Protocol](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent. -| | OpenClaw | NanoBot | **PicoClaw** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Ngôn ngữ** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB*** | -| **Thời gian khởi động**
(CPU 0.8GHz) | >500s | >30s | **<1s** | -| **Chi phí** | Mac Mini $599 | Hầu hết SBC Linux ~$50 | **Mọi bo mạch Linux**
**Chỉ từ $10** | +👁️ **Pipeline thị giác**: Gửi hình ảnh và tệp trực tiếp đến Agent — tự động mã hóa base64 cho LLM đa phương thức. -PicoClaw +🧠 **Định tuyến thông minh**: Định tuyến mô hình dựa trên quy tắc — các truy vấn đơn giản đến mô hình nhẹ, tiết kiệm chi phí API. -> 📋 **[Danh Sách Tương Thích Phần Cứng](docs/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi và điện thoại Android. Board của bạn chưa có? Gửi PR! +_*Các bản build gần đây có thể dùng 10-20MB do merge PR nhanh. Tối ưu hóa tài nguyên đang được lên kế hoạch. So sánh tốc độ khởi động dựa trên benchmark lõi đơn 0.8GHz (xem bảng bên dưới)._ -## 🦾 Demo +
-### 🛠️ Quy trình trợ lý tiêu chuẩn +| | OpenClaw | NanoBot | **PicoClaw** | +| ------------------------------ | ------------- | ------------------------ | -------------------------------------- | +| **Ngôn ngữ** | TypeScript | Python | **Go** | +| **RAM** | >1GB | >100MB | **< 10MB*** | +| **Thời gian khởi động**
(lõi 0.8GHz) | >500s | >30s | **<1s** | +| **Chi phí** | Mac Mini $599 | Hầu hết board Linux ~$50 | **Bất kỳ board Linux**
**từ $10** | - - - - - - - - - - - - - - - - -

🧩 Lập trình Full-Stack

🗂️ Quản lý Nhật ký & Kế hoạch

🔎 Tìm kiếm Web & Học hỏi

Phát triển • Triển khai • Mở rộngLên lịch • Tự động hóa • Ghi nhớKhám phá • Phân tích • Xu hướng
+PicoClaw -### 📱 Chạy trên điện thoại Android cũ +
-Hãy cho chiếc điện thoại cũ một cuộc sống mới! Biến nó thành trợ lý AI thông minh với PicoClaw. Bắt đầu nhanh: +> **[Danh sách Tương thích Phần cứng](docs/vi/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR! -1. **Cài đặt [Termux](https://github.com/termux/termux-app)** (Tải từ [GitHub Releases](https://github.com/termux/termux-app/releases), hoặc tìm trên F-Droid / Google Play). -2. **Chạy các lệnh** +

+PicoClaw Hardware Compatibility +

-```bash -# Tải phiên bản mới nhất từ https://github.com/sipeed/picoclaw/releases -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot cung cấp bố cục hệ thống tệp Linux tiêu chuẩn -``` +## 🦾 Minh họa -Sau đó làm theo hướng dẫn trong phần "Bắt đầu nhanh" để hoàn tất cấu hình! +### 🛠️ Quy trình Trợ lý Tiêu chuẩn -PicoClaw + + + + + + + + + + + + + + + + +

Chế độ Kỹ sư Full-Stack

Ghi nhật ký & Lập kế hoạch

Tìm kiếm Web & Học tập

Phát triển · Triển khai · Mở rộngLên lịch · Tự động hóa · Ghi nhớKhám phá · Thông tin · Xu hướng
-### 🐜 Triển khai sáng tạo trên phần cứng tối thiểu +### 🐜 Triển khai Sáng tạo với Dấu chân Nhỏ -PicoClaw có thể triển khai trên hầu hết mọi thiết bị Linux! +PicoClaw có thể được triển khai trên hầu hết mọi thiết bị Linux! -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E(Ethernet) hoặc W(WiFi6), dùng làm Trợ lý Gia đình tối giản -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) dùng cho quản trị Server tự động -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) dùng cho Giám sát thông minh +- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E(Ethernet) hoặc W(WiFi6), cho trợ lý gia đình tối giản +- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), cho vận hành máy chủ tự động +- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), cho giám sát thông minh -🌟 Nhiều hình thức triển khai hơn đang chờ bạn khám phá! +🌟 Còn nhiều trường hợp triển khai đang chờ đón! ## 📦 Cài đặt -### Tải từ picoclaw.io (Khuyến nghị) +### Tải xuống từ picoclaw.io (Khuyến nghị) -Truy cập **[picoclaw.io](https://picoclaw.io)** — trang web chính thức tự động phát hiện nền tảng của bạn và cung cấp tải xuống một cú nhấp. Không cần chọn kiến trúc thủ công. +Truy cập **[picoclaw.io](https://picoclaw.io)** — website chính thức tự động phát hiện nền tảng của bạn và cung cấp tải xuống một cú nhấp. Không cần chọn kiến trúc thủ công. -### Tải binary đã biên dịch sẵn +### Tải xuống binary đã biên dịch sẵn -Hoặc tải binary cho nền tảng của bạn từ trang [GitHub Releases](https://github.com/sipeed/picoclaw/releases). +Ngoài ra, tải binary cho nền tảng của bạn từ trang [GitHub Releases](https://github.com/sipeed/picoclaw/releases). -### Biên dịch từ mã nguồn (cho phát triển) +### Xây dựng từ mã nguồn (để phát triển) ```bash git clone https://github.com/sipeed/picoclaw.git @@ -178,80 +166,413 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# Build (không cần cài đặt) +# Build core binary make build -# Build cho nhiều nền tảng +# Build Web UI Launcher (required for WebUI mode) +make build-launcher + +# Build for multiple platforms make build-all -# Build cho Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) +# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64) make build-pi-zero -# Build và cài đặt +# Build and install make install ``` -**Raspberry Pi Zero 2 W:** Sử dụng binary phù hợp với hệ điều hành: Raspberry Pi OS 32-bit → `make build-linux-arm`; 64-bit → `make build-linux-arm64`. Hoặc chạy `make build-pi-zero` để build cả hai. +**Raspberry Pi Zero 2 W:** Sử dụng binary phù hợp với hệ điều hành của bạn: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Hoặc chạy `make build-pi-zero` để xây dựng cả hai. -## 📚 Tài liệu +## 🚀 Hướng dẫn Khởi động Nhanh -Để xem hướng dẫn chi tiết, tham khảo tài liệu bên dưới. README này chỉ bao gồm phần bắt đầu nhanh. +### 🌐 WebUI Launcher (Khuyến nghị cho Desktop) -| Chủ đề | Mô tả | -|--------|-------| -| 🐳 [Docker & Bắt đầu nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent, cấu hình Bắt đầu nhanh | -| 💬 [Ứng dụng Chat](docs/vi/chat-apps.md) | Telegram, Discord, WhatsApp, Matrix, QQ, Slack, IRC, DingTalk, LINE, Feishu, WeCom và nhiều hơn | -| ⚙️ [Cấu hình](docs/vi/configuration.md) | Biến môi trường, cấu trúc workspace, nguồn skill, sandbox bảo mật, heartbeat | -| 🔌 [Nhà cung cấp & Mô hình](docs/vi/providers.md) | 20+ nhà cung cấp LLM, định tuyến mô hình, cấu hình model_list, kiến trúc nhà cung cấp | -| 🔄 [Spawn & Tác vụ bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ | -| 🐛 [Xử lý sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp | -| 🔧 [Cấu hình Công cụ](docs/vi/tools_configuration.md) | Bật/tắt từng công cụ, chính sách thực thi | -| 📋 [Tương Thích Phần Cứng](docs/hardware-compatibility.md) | Các board đã kiểm tra, yêu cầu tối thiểu, cách thêm board | +WebUI Launcher cung cấp giao diện dựa trên trình duyệt để cấu hình và trò chuyện. Đây là cách dễ nhất để bắt đầu — không cần kiến thức dòng lệnh. + +**Tùy chọn 1: Nhấp đúp (Desktop)** + +Sau khi tải xuống từ [picoclaw.io](https://picoclaw.io), nhấp đúp vào `picoclaw-launcher` (hoặc `picoclaw-launcher.exe` trên Windows). Trình duyệt của bạn sẽ tự động mở tại `http://localhost:18800`. + +**Tùy chọn 2: Dòng lệnh** + +```bash +picoclaw-launcher +# Mở http://localhost:18800 trong trình duyệt của bạn +``` + +> [!TIP] +> **Truy cập từ xa / Docker / VM:** Thêm cờ `-public` để lắng nghe trên tất cả giao diện: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**Bắt đầu:** + +Mở WebUI, sau đó: **1)** Cấu hình Provider (thêm API key LLM của bạn) -> **2)** Cấu hình Channel (ví dụ: Telegram) -> **3)** Khởi động Gateway -> **4)** Trò chuyện! + +Để biết tài liệu WebUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io). + +
+Docker (thay thế) + +```bash +# 1. Clone this repo +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. First run — auto-generates docker/data/config.json then exits +# (only triggers when both config.json and workspace/ are missing) +docker compose -f docker/docker-compose.yml --profile launcher up +# The container prints "First-run setup complete." and stops. + +# 3. Set your API keys +vim docker/data/config.json + +# 4. Start +docker compose -f docker/docker-compose.yml --profile launcher up -d +# Open http://localhost:18800 +``` + +> **Người dùng Docker / VM:** Gateway lắng nghe trên `127.0.0.1` theo mặc định. Đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` hoặc dùng cờ `-public` để có thể truy cập từ host. + +```bash +# Check logs +docker compose -f docker/docker-compose.yml logs -f + +# Stop +docker compose -f docker/docker-compose.yml --profile launcher down + +# Update +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher (Khuyến nghị cho Headless / SSH) + +TUI (Terminal UI) Launcher cung cấp giao diện terminal đầy đủ tính năng để cấu hình và quản lý. Lý tưởng cho máy chủ, Raspberry Pi và các môi trường headless khác. + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**Bắt đầu:** + +Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Channel -> **3)** Khởi động Gateway -> **4)** Trò chuyện! + +Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io). + +### 📱 Android + +Hãy cho chiếc điện thoại cũ của bạn một cuộc sống mới! Biến nó thành Trợ lý AI thông minh với PicoClaw. + +**Tùy chọn 1: Termux (có sẵn ngay)** + +1. Cài đặt [Termux](https://github.com/termux/termux-app) (tải từ [GitHub Releases](https://github.com/termux/termux-app/releases), hoặc tìm kiếm trong F-Droid / Google Play) +2. Chạy các lệnh sau: + +```bash +# Download the latest release +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem layout +``` + +Sau đó làm theo phần Terminal Launcher bên dưới để hoàn tất cấu hình. + +PicoClaw on Termux + +**Tùy chọn 2: Cài đặt APK (sắp ra mắt)** + +Một APK Android độc lập với WebUI tích hợp đang được phát triển. Hãy đón chờ! + +
+Terminal Launcher (cho môi trường hạn chế tài nguyên) + +Đối với các môi trường tối giản chỉ có binary lõi `picoclaw` (không có Launcher UI), bạn có thể cấu hình mọi thứ qua dòng lệnh và tệp cấu hình JSON. + +**1. Khởi tạo** + +```bash +picoclaw onboard +``` + +Lệnh này tạo `~/.picoclaw/config.json` và thư mục workspace. + +**2. Cấu hình** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> Xem `config/config.example.json` trong repo để có mẫu cấu hình đầy đủ với tất cả các tùy chọn có sẵn. + +**3. Trò chuyện** + +```bash +# One-shot question +picoclaw agent -m "What is 2+2?" + +# Interactive mode +picoclaw agent + +# Start gateway for chat app integration +picoclaw gateway +``` + +
+ +## 🔌 Providers (LLM) + +PicoClaw hỗ trợ 30+ Provider LLM thông qua cấu hình `model_list`. Sử dụng định dạng `protocol/model`: + +| Provider | Protocol | API Key | Ghi chú | +|----------|----------|---------|---------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Bắt buộc | GPT-5.4, GPT-4o, o3, v.v. | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Bắt buộc | Claude Opus 4.6, Sonnet 4.6, v.v. | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Bắt buộc | Gemini 3 Flash, 2.5 Pro, v.v. | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Bắt buộc | 200+ mô hình, API thống nhất | +| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Bắt buộc | GLM-4.7, GLM-5, v.v. | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Bắt buộc | DeepSeek-V3, DeepSeek-R1 | +| [Volcengine](https://console.volcengine.com) | `volcengine/` | Bắt buộc | Doubao, Ark models | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Bắt buộc | Qwen3, Qwen-Max, v.v. | +| [Groq](https://console.groq.com/keys) | `groq/` | Bắt buộc | Suy luận nhanh (Llama, Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Bắt buộc | Kimi models | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Bắt buộc | MiniMax models | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Bắt buộc | Mistral Large, Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Bắt buộc | Mô hình do NVIDIA lưu trữ | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Bắt buộc | Suy luận nhanh | +| [Novita AI](https://novita.ai/) | `novita/` | Bắt buộc | Nhiều mô hình mở | +| [Ollama](https://ollama.com/) | `ollama/` | Không cần | Mô hình cục bộ, tự lưu trữ | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | Không cần | Triển khai cục bộ, tương thích OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Tùy | Proxy cho 100+ provider | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Bắt buộc | Triển khai Azure doanh nghiệp | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Đăng nhập bằng device code | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+Triển khai cục bộ (Ollama, vLLM, v.v.) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](docs/vi/providers.md). + +
+ +## 💬 Channels (Ứng dụng Chat) + +Trò chuyện với PicoClaw của bạn qua 17+ nền tảng nhắn tin: + +| Channel | Thiết lập | Protocol | Tài liệu | +|---------|-----------|----------|----------| +| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](docs/channels/telegram/README.vi.md) | +| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](docs/channels/discord/README.vi.md) | +| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](docs/vi/chat-apps.md#whatsapp) | +| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](docs/vi/chat-apps.md#weixin) | +| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](docs/channels/qq/README.vi.md) | +| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](docs/channels/slack/README.vi.md) | +| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](docs/channels/matrix/README.vi.md) | +| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](docs/channels/dingtalk/README.vi.md) | +| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](docs/channels/feishu/README.vi.md) | +| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](docs/channels/line/README.vi.md) | +| **WeCom Bot** | Trung bình (webhook URL) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_bot/README.vi.md) | +| **WeCom App** | Trung bình (corp credentials) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_app/README.vi.md) | +| **WeCom AI Bot** | Trung bình (token + AES key) | WebSocket / Webhook | [Hướng dẫn](docs/channels/wecom/wecom_aibot/README.vi.md) | +| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](docs/vi/chat-apps.md#irc) | +| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](docs/channels/onebot/README.vi.md) | +| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](docs/channels/maixcam/README.vi.md) | +| **Pico** | Dễ (bật) | Native protocol | Tích hợp sẵn | +| **Pico Client** | Dễ (WebSocket URL) | WebSocket | Tích hợp sẵn | + +> Tất cả các Channel dựa trên webhook dùng chung một Gateway HTTP server (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Feishu sử dụng chế độ WebSocket/SDK và không dùng HTTP server chung. + +Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](docs/vi/chat-apps.md). + +## 🔧 Tools + +### 🔍 Tìm kiếm Web + +PicoClaw có thể tìm kiếm web để cung cấp thông tin cập nhật. Cấu hình trong `tools.web`: + +| Công cụ Tìm kiếm | API Key | Gói miễn phí | Liên kết | +|------------------|---------|--------------|----------| +| DuckDuckGo | Không cần | Không giới hạn | Dự phòng tích hợp sẵn | +| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Bắt buộc | 1000 truy vấn/ngày | AI, tối ưu cho tiếng Trung | +| [Tavily](https://tavily.com) | Bắt buộc | 1000 truy vấn/tháng | Tối ưu cho AI Agent | +| [Brave Search](https://brave.com/search/api) | Bắt buộc | 2000 truy vấn/tháng | Nhanh và riêng tư | +| [Perplexity](https://www.perplexity.ai) | Bắt buộc | Trả phí | Tìm kiếm hỗ trợ AI | +| [SearXNG](https://github.com/searxng/searxng) | Không cần | Tự lưu trữ | Metasearch engine miễn phí | +| [GLM Search](https://open.bigmodel.cn/) | Bắt buộc | Tùy | Tìm kiếm web Zhipu | + +### ⚙️ Các Tools Khác + +PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](docs/vi/tools_configuration.md) để biết chi tiết. + +## 🎯 Skills + +Skills là các khả năng mô-đun mở rộng Agent của bạn. Chúng được tải từ các tệp `SKILL.md` trong workspace của bạn. + +**Cài đặt Skills từ ClawHub:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**Cấu hình token ClawHub** (tùy chọn, để có giới hạn tốc độ cao hơn): + +Thêm vào `config.json` của bạn: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](docs/vi/tools_configuration.md#skills-tool). + +## 🔗 MCP (Model Context Protocol) + +PicoClaw hỗ trợ [MCP](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent của bạn với các tool và nguồn dữ liệu bên ngoài. + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](docs/vi/tools_configuration.md#mcp-tool). ## ClawdChat Tham gia Mạng xã hội Agent -Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn qua CLI hoặc bất kỳ ứng dụng Chat nào đã tích hợp. +Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn duy nhất qua CLI hoặc bất kỳ Ứng dụng Chat nào đã tích hợp. **Đọc `https://clawdchat.ai/skill.md` và làm theo hướng dẫn để tham gia [ClawdChat.ai](https://clawdchat.ai)** ## 🖥️ Tham chiếu CLI -| Lệnh | Mô tả | -| -------------------------- | ------------------------------ | -| `picoclaw onboard` | Khởi tạo cấu hình & workspace | -| `picoclaw agent -m "..."` | Trò chuyện với agent | -| `picoclaw agent` | Chế độ chat tương tác | -| `picoclaw gateway` | Khởi động gateway | -| `picoclaw status` | Hiển thị trạng thái | -| `picoclaw version` | Hiển thị thông tin phiên bản | -| `picoclaw cron list` | Liệt kê tất cả tác vụ định kỳ | -| `picoclaw cron add ...` | Thêm tác vụ định kỳ | -| `picoclaw cron disable` | Tắt tác vụ định kỳ | -| `picoclaw cron remove` | Xóa tác vụ định kỳ | -| `picoclaw skills list` | Liệt kê các skill đã cài | -| `picoclaw skills install` | Cài đặt một skill | -| `picoclaw migrate` | Di chuyển dữ liệu từ phiên bản cũ | -| `picoclaw auth login` | Xác thực với nhà cung cấp | -| `picoclaw model` | Xem hoặc chuyển đổi model mặc định | - -### Tác vụ định kỳ / Nhắc nhở - -PicoClaw hỗ trợ nhắc nhở theo lịch và tác vụ lặp lại thông qua công cụ `cron`: - -* **Nhắc nhở một lần**: "Nhắc tôi sau 10 phút" → kích hoạt một lần sau 10 phút -* **Tác vụ lặp lại**: "Nhắc tôi mỗi 2 giờ" → kích hoạt mỗi 2 giờ -* **Biểu thức Cron**: "Nhắc tôi lúc 9 giờ sáng mỗi ngày" → sử dụng biểu thức cron +| Lệnh | Mô tả | +| ------------------------- | ---------------------------------------- | +| `picoclaw onboard` | Khởi tạo cấu hình & workspace | +| `picoclaw onboard weixin` | Kết nối tài khoản WeChat qua QR | +| `picoclaw agent -m "..."` | Trò chuyện với agent | +| `picoclaw agent` | Chế độ trò chuyện tương tác | +| `picoclaw gateway` | Khởi động gateway | +| `picoclaw status` | Hiển thị trạng thái | +| `picoclaw version` | Hiển thị thông tin phiên bản | +| `picoclaw model` | Xem hoặc chuyển đổi mô hình mặc định | +| `picoclaw cron list` | Liệt kê tất cả công việc đã lên lịch | +| `picoclaw cron add ...` | Thêm công việc đã lên lịch | +| `picoclaw cron disable` | Vô hiệu hóa công việc đã lên lịch | +| `picoclaw cron remove` | Xóa công việc đã lên lịch | +| `picoclaw skills list` | Liệt kê các Skill đã cài đặt | +| `picoclaw skills install` | Cài đặt một Skill | +| `picoclaw migrate` | Di chuyển dữ liệu từ các phiên bản cũ | +| `picoclaw auth login` | Xác thực với các provider | + +### ⏰ Tác vụ Đã lên lịch / Nhắc nhở + +PicoClaw hỗ trợ nhắc nhở đã lên lịch và tác vụ định kỳ thông qua tool `cron`: + +* **Nhắc nhở một lần**: "Nhắc tôi sau 10 phút" -> kích hoạt một lần sau 10 phút +* **Tác vụ định kỳ**: "Nhắc tôi mỗi 2 giờ" -> kích hoạt mỗi 2 giờ +* **Biểu thức Cron**: "Nhắc tôi lúc 9 giờ sáng hàng ngày" -> sử dụng biểu thức cron + +## 📚 Tài liệu + +Để biết các hướng dẫn chi tiết ngoài README này: + +| Chủ đề | Mô tả | +|--------|-------| +| [Docker & Khởi động Nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent | +| [Ứng dụng Chat](docs/vi/chat-apps.md) | Hướng dẫn thiết lập 17+ Channel | +| [Cấu hình](docs/vi/configuration.md) | Biến môi trường, bố cục workspace, sandbox bảo mật | +| [Providers & Models](docs/vi/providers.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list | +| [Spawn & Tác vụ Bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ | +| [Hooks](docs/hooks/README.md) | Hệ thống hook hướng sự kiện: observer, interceptor, approval hook | +| [Steering](docs/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy | +| [SubTurn](docs/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời | +| [Khắc phục sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp | +| [Cấu hình Tools](docs/vi/tools_configuration.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills | +| [Tương thích Phần cứng](docs/vi/hardware-compatibility.md) | Các board đã kiểm tra, yêu cầu tối thiểu | ## 🤝 Đóng góp & Lộ trình -Chào đón mọi PR! Mã nguồn được thiết kế nhỏ gọn và dễ đọc. 🤗 +PR luôn được chào đón! Codebase được thiết kế nhỏ gọn và dễ đọc. -Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md) đầy đủ. +Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn. -Nhóm phát triển đang được xây dựng. Tham gia sau khi có PR đầu tiên được merge! +Nhóm nhà phát triển đang được xây dựng, tham gia sau khi PR đầu tiên của bạn được merge! -Nhóm người dùng: +Nhóm Người dùng: -discord: +Discord: -PicoClaw +WeChat: +WeChat group QR code diff --git a/README.zh.md b/README.zh.md index 1bc5d1a4b7..de96e5164a 100644 --- a/README.zh.md +++ b/README.zh.md @@ -3,7 +3,7 @@

PicoClaw: 基于Go语言的超高效 AI 助手

-

$10 硬件 · <10MB 内存 · <1s 启动 · 皮皮虾,我们走!

+

$10 硬件 · 10MB 内存 · 毫秒启动 · 皮皮虾,我们走!

Go Hardware @@ -95,6 +95,8 @@ _*近期版本因快速合并 PR 可能占用 10–20MB,资源优化已列入计划。启动速度对比基于 0.8GHz 单核实测(见下方对比表)。_ +

+ | | OpenClaw | NanoBot | **PicoClaw** | | ------------------------------ | ------------- | ------------------------ | -------------------------------------- | | **语言** | TypeScript | Python | **Go** | @@ -104,7 +106,13 @@ _*近期版本因快速合并 PR 可能占用 10–20MB,资源优化已列入 PicoClaw -> 📋 **[硬件兼容列表](docs/hardware-compatibility.md)** — 查看所有已测试的板卡,从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中?欢迎提交 PR! +
+ +> 📋 **[硬件兼容列表](docs/zh/hardware-compatibility.md)** — 查看所有已测试的板卡,从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中?欢迎提交 PR! + +

+PicoClaw Hardware Compatibility +

## 🦾 演示 @@ -128,25 +136,6 @@ _*近期版本因快速合并 PR 可能占用 10–20MB,资源优化已列入 -### 📱 在手机上轻松运行 - -PicoClaw 可以将你 10 年前的老旧手机废物利用,变身成为你的 AI 助理!快速指南: - -1. 安装 [Termux](https://github.com/termux/termux-app)(可从 [GitHub Releases](https://github.com/termux/termux-app/releases) 下载,或在 F-Droid 等应用商店搜索) -2. 打开后执行指令 - -```bash -# 从 Release 页面下载最新版本 -wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz -tar xzf picoclaw_Linux_arm64.tar.gz -pkg install proot -termux-chroot ./picoclaw onboard # chroot 提供标准 Linux 文件系统布局 -``` - -然后跟随下面的"快速开始"章节继续配置 PicoClaw 即可使用! - -PicoClaw - ### 🐜 创新的低占用部署 PicoClaw 几乎可以部署在任何 Linux 设备上! @@ -177,9 +166,12 @@ git clone https://github.com/sipeed/picoclaw.git cd picoclaw make deps -# 构建(无需安装) +# 构建核心二进制文件 make build +# 构建 Web UI Launcher(WebUI 模式必需) +make build-launcher + # 为多平台构建 make build-all @@ -192,20 +184,330 @@ make install **Raspberry Pi Zero 2 W:** 请使用与系统匹配的二进制文件:32 位 Raspberry Pi OS → `make build-linux-arm`;64 位 → `make build-linux-arm64`。或运行 `make build-pi-zero` 同时构建两者。 -## 📚 文档 +## 🚀 快速开始 -详细指南请参阅以下文档,README 仅涵盖快速入门。 +### 🌐 WebUI Launcher(推荐桌面用户) -| 主题 | 说明 | -|------|------| -| 🐳 [Docker 与快速开始](docs/zh/docker.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 | -| 💬 [聊天应用配置](docs/zh/chat-apps.md) | Telegram、Discord、WhatsApp、Matrix、QQ、Slack、IRC、钉钉、LINE、飞书、企业微信等 | -| ⚙️ [配置指南](docs/zh/configuration.md) | 环境变量、工作区布局、技能来源、安全沙箱、心跳任务 | -| 🔌 [提供商与模型配置](docs/zh/providers.md) | 20+ LLM 提供商、模型路由、model_list 配置、Provider 架构 | -| 🔄 [异步任务与 Spawn](docs/zh/spawn-tasks.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 | -| 🐛 [疑难解答](docs/zh/troubleshooting.md) | 常见问题与解决方案 | -| 🔧 [工具配置](docs/zh/tools_configuration.md) | 工具启用/禁用、执行策略 | -| 📋 [硬件兼容列表](docs/hardware-compatibility.md) | 已测试板卡、最低要求、如何添加你的板卡 | +WebUI Launcher 提供基于浏览器的配置与聊天界面,是最简单的上手方式——无需命令行知识。 + +**方式一:双击启动(桌面)** + +从 [picoclaw.io](https://picoclaw.io) 下载后,双击 `picoclaw-launcher`(Windows 上为 `picoclaw-launcher.exe`),浏览器将自动打开 `http://localhost:18800`。 + +**方式二:命令行** + +```bash +picoclaw-launcher +# 在浏览器中打开 http://localhost:18800 +``` + +> [!TIP] +> **远程访问 / Docker / 虚拟机:** 添加 `-public` 参数以监听所有网络接口: +> ```bash +> picoclaw-launcher -public +> ``` + +

+WebUI Launcher +

+ +**开始使用:** + +打开 WebUI,然后:**1)** 配置 Provider(填入 LLM API Key)-> **2)** 配置 Channel(如 Telegram)-> **3)** 启动 Gateway -> **4)** 开始聊天! + +详细 WebUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。 + +
+Docker(备选方案) + +```bash +# 1. 克隆本仓库 +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 2. 首次运行——自动生成 docker/data/config.json 后退出 +# (仅在 config.json 和 workspace/ 均不存在时触发) +docker compose -f docker/docker-compose.yml --profile launcher up +# 容器打印 "First-run setup complete." 后停止。 + +# 3. 填写 API Key +vim docker/data/config.json + +# 4. 启动 +docker compose -f docker/docker-compose.yml --profile launcher up -d +# 打开 http://localhost:18800 +``` + +> **Docker / 虚拟机用户:** Gateway 默认监听 `127.0.0.1`。设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或使用 `-public` 参数以允许从宿主机访问。 + +```bash +# 查看日志 +docker compose -f docker/docker-compose.yml logs -f + +# 停止 +docker compose -f docker/docker-compose.yml --profile launcher down + +# 更新 +docker compose -f docker/docker-compose.yml pull +docker compose -f docker/docker-compose.yml --profile launcher up -d +``` + +
+ +### 💻 TUI Launcher(推荐无头环境 / SSH) + +TUI(终端 UI)Launcher 提供功能完整的终端配置与管理界面,适合服务器、树莓派等无显示器环境。 + +```bash +picoclaw-launcher-tui +``` + +

+TUI Launcher +

+ +**开始使用:** + +通过 TUI 菜单:**1)** 配置 Provider -> **2)** 配置 Channel -> **3)** 启动 Gateway -> **4)** 开始聊天! + +详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。 + +### 📱 Android + +让你十年前的旧手机焕发新生!将它变成你的 AI 助手。 + +**方式一:Termux(现已可用)** + +1. 安装 [Termux](https://github.com/termux/termux-app)(可从 [GitHub Releases](https://github.com/termux/termux-app/releases) 下载,或在 F-Droid / Google Play 中搜索) +2. 执行以下命令: + +```bash +# 从 Release 页面下载最新版本 +wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz +tar xzf picoclaw_Linux_arm64.tar.gz +pkg install proot +termux-chroot ./picoclaw onboard # chroot 提供标准 Linux 文件系统布局 +``` + +然后跟随下面的"Terminal Launcher"章节继续配置。 + +PicoClaw on Termux + +**方式二:APK 安装(即将推出)** + +内置 WebUI 的独立 Android APK 正在开发中,敬请期待! + +
+Terminal Launcher(适用于资源受限环境) + +对于只有 `picoclaw` 核心二进制文件的极简环境(无 Launcher UI),可通过命令行和 JSON 配置文件完成所有配置。 + +**1. 初始化** + +```bash +picoclaw onboard +``` + +此命令会创建 `~/.picoclaw/config.json` 和工作区目录。 + +**2. 配置** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "model_name": "gpt-5.4" + } + }, + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-api-key" + } + ] +} +``` + +> 完整配置模板请参阅仓库中的 `config/config.example.json`。 + +**3. 开始聊天** + +```bash +# 单次提问 +picoclaw agent -m "What is 2+2?" + +# 交互式对话模式 +picoclaw agent + +# 启动 Gateway 以接入聊天应用 +picoclaw gateway +``` + +
+ +## 🔌 Providers (LLM) + +PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider,使用 `协议/模型` 格式: + +| Provider | 协议 | API Key | 备注 | +|----------|------|---------|------| +| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必填 | GPT-5.4、GPT-4o、o3 等 | +| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必填 | Claude Opus 4.6、Sonnet 4.6 等 | +| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必填 | Gemini 3 Flash、2.5 Pro 等 | +| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必填 | 200+ 模型,统一 API | +| [智谱 (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必填 | GLM-4.7、GLM-5 等 | +| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必填 | DeepSeek-V3、DeepSeek-R1 | +| [火山引擎](https://console.volcengine.com) | `volcengine/` | 必填 | 豆包、Ark 系列模型 | +| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必填 | Qwen3、Qwen-Max 等 | +| [Groq](https://console.groq.com/keys) | `groq/` | 必填 | 快速推理(Llama、Mixtral) | +| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必填 | Kimi 系列模型 | +| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必填 | MiniMax 系列模型 | +| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必填 | Mistral Large、Codestral | +| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必填 | NVIDIA 托管模型 | +| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必填 | 快速推理 | +| [Novita AI](https://novita.ai/) | `novita/` | 必填 | 多种开源模型 | +| [Ollama](https://ollama.com/) | `ollama/` | 无需 | 本地模型,自托管 | +| [vLLM](https://docs.vllm.ai/) | `vllm/` | 无需 | 本地部署,兼容 OpenAI | +| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 视情况 | 100+ Provider 代理 | +| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必填 | 企业级 Azure 部署 | +| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | 设备码登录 | +| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI | + +
+本地部署(Ollama、vLLM 等) + +**Ollama:** +```json +{ + "model_list": [ + { + "model_name": "local-llama", + "model": "ollama/llama3.1:8b", + "api_base": "http://localhost:11434/v1" + } + ] +} +``` + +**vLLM:** +```json +{ + "model_list": [ + { + "model_name": "local-vllm", + "model": "vllm/your-model", + "api_base": "http://localhost:8000/v1" + } + ] +} +``` + +完整 Provider 配置详情请参阅 [Providers & Models](docs/zh/providers.md)。 + +
+ +## 💬 Channels(聊天应用) + +通过 17+ 消息平台与你的 PicoClaw 对话: + +| Channel | 配置难度 | 协议 | 文档 | +|---------|----------|------|------| +| **Telegram** | 简单(bot token) | 长轮询 | [指南](docs/channels/telegram/README.zh.md) | +| **Discord** | 简单(bot token + intents) | WebSocket | [指南](docs/channels/discord/README.zh.md) | +| **WhatsApp** | 简单(扫码或 bridge URL) | 原生 / Bridge | [指南](docs/zh/chat-apps.md#whatsapp) | +| **微信 (Weixin)** | 简单(扫码登录) | iLink API | [指南](docs/zh/chat-apps.md#weixin) | +| **QQ** | 简单(AppID + AppSecret) | WebSocket | [指南](docs/channels/qq/README.zh.md) | +| **Slack** | 简单(bot + app token) | Socket Mode | [指南](docs/channels/slack/README.zh.md) | +| **Matrix** | 中等(homeserver + token) | Sync API | [指南](docs/channels/matrix/README.zh.md) | +| **钉钉** | 中等(client credentials) | Stream | [指南](docs/channels/dingtalk/README.zh.md) | +| **飞书 / Lark** | 中等(App ID + Secret) | WebSocket/SDK | [指南](docs/channels/feishu/README.zh.md) | +| **LINE** | 中等(credentials + webhook) | Webhook | [指南](docs/channels/line/README.zh.md) | +| **企业微信机器人** | 中等(webhook URL) | Webhook | [指南](docs/channels/wecom/wecom_bot/README.zh.md) | +| **企业微信应用** | 中等(corp credentials) | Webhook | [指南](docs/channels/wecom/wecom_app/README.zh.md) | +| **企业微信 AI 机器人** | 中等(token + AES key) | WebSocket / Webhook | [指南](docs/channels/wecom/wecom_aibot/README.zh.md) | +| **IRC** | 中等(server + nick) | IRC 协议 | [指南](docs/zh/chat-apps.md#irc) | +| **OneBot** | 中等(WebSocket URL) | OneBot v11 | [指南](docs/channels/onebot/README.zh.md) | +| **MaixCam** | 简单(启用即可) | TCP socket | [指南](docs/channels/maixcam/README.zh.md) | +| **Pico** | 简单(启用即可) | 原生协议 | 内置 | +| **Pico Client** | 简单(WebSocket URL) | WebSocket | 内置 | + +> 所有基于 Webhook 的 Channel 共用同一个 Gateway HTTP 服务器(`gateway.host`:`gateway.port`,默认 `127.0.0.1:18790`)。飞书使用 WebSocket/SDK 模式,不使用共享 HTTP 服务器。 + +详细 Channel 配置说明请参阅 [聊天应用配置](docs/zh/chat-apps.md)。 + +## 🔧 Tools + +### 🔍 网络搜索 + +PicoClaw 可以搜索网络以提供最新信息。在 `tools.web` 中配置: + +| 搜索引擎 | API Key | 免费额度 | 链接 | +|---------|---------|---------|------| +| [百度搜索](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必填 | 1000 次/天 | AI 搜索,国内首选 | +| [Tavily](https://tavily.com) | 必填 | 1000 次/月 | 专为 AI Agent 优化 | +| [GLM Search](https://open.bigmodel.cn/) | 必填 | 视情况 | 智谱网络搜索 | +| DuckDuckGo | 无需 | 无限制 | 内置备用(国内访问困难) | +| [Perplexity](https://www.perplexity.ai) | 必填 | 付费 | AI 驱动搜索(国内访问困难) | +| [Brave Search](https://brave.com/search/api) | 必填 | 2000 次/月 | 快速且注重隐私(国内访问困难) | +| [SearXNG](https://github.com/searxng/searxng) | 无需 | 自托管 | 免费元搜索引擎 | + +### ⚙️ 其他工具 + +PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](docs/zh/tools_configuration.md)。 + +## 🎯 Skills + +Skills 是扩展 Agent 能力的模块化插件,从工作区的 `SKILL.md` 文件加载。 + +**从 ClawHub 安装 Skills:** + +```bash +picoclaw skills search "web scraping" +picoclaw skills install +``` + +**配置 ClawHub token**(可选,用于提高速率限制): + +在 `config.json` 中添加: +```json +{ + "tools": { + "skills": { + "registries": { + "clawhub": { + "auth_token": "your-clawhub-token" + } + } + } + } +} +``` + +更多详情请参阅 [工具配置 - Skills](docs/zh/tools_configuration.md#skills-tool)。 + +## 🔗 MCP (Model Context Protocol) + +PicoClaw 原生支持 [MCP](https://modelcontextprotocol.io/) — 连接任意 MCP 服务器,通过外部工具和数据源扩展 Agent 能力。 + +```json +{ + "tools": { + "mcp": { + "enabled": true, + "servers": { + "filesystem": { + "enabled": true, + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } + } + } +} +``` + +完整 MCP 配置(stdio、SSE、HTTP 传输、Tool Discovery)请参阅 [工具配置 - MCP](docs/zh/tools_configuration.md#mcp-tool)。 ## ClawdChat 加入 Agent 社交网络 @@ -218,23 +520,23 @@ make install | 命令 | 说明 | | ------------------------- | ---------------------- | | `picoclaw onboard` | 初始化配置与工作区 | -| `picoclaw onboard weixin` | 扫码连接微信个人号 | +| `picoclaw onboard weixin` | 扫码连接微信个人号 | | `picoclaw agent -m "..."` | 与 Agent 对话 | | `picoclaw agent` | 交互式对话模式 | | `picoclaw gateway` | 启动网关 | | `picoclaw status` | 查看状态 | | `picoclaw version` | 查看版本信息 | +| `picoclaw model` | 查看或切换默认模型 | | `picoclaw cron list` | 列出所有定时任务 | | `picoclaw cron add ...` | 添加定时任务 | | `picoclaw cron disable` | 禁用定时任务 | | `picoclaw cron remove` | 删除定时任务 | -| `picoclaw skills list` | 列出已安装技能 | -| `picoclaw skills install` | 安装技能 | +| `picoclaw skills list` | 列出已安装 Skills | +| `picoclaw skills install` | 安装 Skill | | `picoclaw migrate` | 从旧版本迁移数据 | -| `picoclaw auth login` | 认证提供商 | -| `picoclaw model` | 查看或切换默认模型 | +| `picoclaw auth login` | 认证 Provider | -### 定时任务 / 提醒 +### ⏰ 定时任务 / 提醒 PicoClaw 通过 `cron` 工具支持定时提醒和重复任务: @@ -242,11 +544,29 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务: * **重复任务**: "每2小时提醒我" → 每2小时触发 * **Cron 表达式**: "每天上午9点提醒我" → 使用 cron 表达式 +## 📚 文档 + +详细指南请参阅以下文档,README 仅涵盖快速入门。 + +| 主题 | 说明 | +|------|------| +| 🐳 [Docker 与快速开始](docs/zh/docker.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 | +| 💬 [聊天应用配置](docs/zh/chat-apps.md) | 全部 17+ Channel 配置指南 | +| ⚙️ [配置指南](docs/zh/configuration.md) | 环境变量、工作区布局、安全沙箱 | +| 🔌 [提供商与模型配置](docs/zh/providers.md) | 30+ LLM Provider、模型路由、model_list 配置 | +| 🔄 [异步任务与 Spawn](docs/zh/spawn-tasks.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 | +| 🪝 [Hook 系统](docs/hooks/README.zh.md) | 事件驱动 Hook:观察者、拦截器、审批 Hook | +| 🎯 [Steering](docs/steering.md) | 在工具调用间向运行中的 Agent 注入消息 | +| 🔀 [SubTurn](docs/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 | +| 🐛 [疑难解答](docs/zh/troubleshooting.md) | 常见问题与解决方案 | +| 🔧 [工具配置](docs/zh/tools_configuration.md) | 工具启用/禁用、执行策略、MCP、Skills | +| 📋 [硬件兼容列表](docs/zh/hardware-compatibility.md) | 已测试板卡、最低要求 | + ## 🤝 贡献与路线图 欢迎提交 PR!代码库刻意保持小巧和可读。🤗 -查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md)。 +查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。 开发者群组正在组建中,入群门槛:至少合并过 1 个 PR。 @@ -254,4 +574,10 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务: Discord: -PicoClaw +WeChat: +WeChat group QR code + + + + + diff --git a/docs/channels/matrix/README.fr.md b/docs/channels/matrix/README.fr.md new file mode 100644 index 0000000000..ec762a8b88 --- /dev/null +++ b/docs/channels/matrix/README.fr.md @@ -0,0 +1,64 @@ +> Retour au [README](../../../README.fr.md) + +# Guide de configuration du canal Matrix + +## 1. Exemple de configuration + +Ajoutez ceci à `config.json` : + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "user_id": "@your-bot:matrix.org", + "access_token": "YOUR_MATRIX_ACCESS_TOKEN", + "device_id": "", + "join_on_invite": true, + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "placeholder": { + "enabled": true, + "text": "Thinking..." + }, + "reasoning_channel_id": "", + "message_format": "richtext" + } + } +} +``` + +## 2. Référence des champs + +| Champ | Type | Requis | Description | +|----------------------|----------|--------|-------------| +| enabled | bool | Oui | Activer ou désactiver le canal Matrix | +| homeserver | string | Oui | URL du homeserver Matrix (par exemple `https://matrix.org`) | +| user_id | string | Oui | ID utilisateur Matrix du bot (par exemple `@bot:matrix.org`) | +| access_token | string | Oui | Jeton d'accès du bot | +| device_id | string | Non | ID d'appareil Matrix optionnel | +| join_on_invite | bool | Non | Rejoindre automatiquement les salons invités | +| allow_from | []string | Non | Liste blanche d'utilisateurs (IDs Matrix) | +| group_trigger | object | Non | Stratégie de déclenchement de groupe (`mention_only` / `prefixes`) | +| placeholder | object | Non | Configuration du message de remplacement | +| reasoning_channel_id | string | Non | Canal cible pour la sortie de raisonnement | +| message_format | string | Non | Format de sortie : `"richtext"` (défaut) rend le markdown en HTML ; `"plain"` envoie du texte brut uniquement | + +## 3. Fonctionnalités actuellement supportées + +- Envoi/réception de messages texte avec rendu markdown (gras, italique, titres, blocs de code, etc.) +- Format de message configurable (`richtext` / `plain`) +- Téléchargement d'images/audio/vidéo/fichiers entrants (MediaStore en priorité, chemin local en secours) +- Normalisation de l'audio entrant dans le flux de transcription existant (`[audio: ...]`) +- Upload et envoi d'images/audio/vidéo/fichiers sortants +- Règles de déclenchement de groupe (y compris le mode mention uniquement) +- État de frappe (`m.typing`) +- Message de remplacement + remplacement de la réponse finale +- Rejoindre automatiquement les salons invités (peut être désactivé) + +## 4. TODO + +- Améliorations des métadonnées des médias riches (par exemple taille et miniatures des images/vidéos) diff --git a/docs/channels/matrix/README.ja.md b/docs/channels/matrix/README.ja.md new file mode 100644 index 0000000000..e5a773d4d8 --- /dev/null +++ b/docs/channels/matrix/README.ja.md @@ -0,0 +1,64 @@ +> [README](../../../README.ja.md) に戻る + +# Matrix チャンネル設定ガイド + +## 1. 設定例 + +`config.json` に以下を追加してください: + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "user_id": "@your-bot:matrix.org", + "access_token": "YOUR_MATRIX_ACCESS_TOKEN", + "device_id": "", + "join_on_invite": true, + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "placeholder": { + "enabled": true, + "text": "Thinking..." + }, + "reasoning_channel_id": "", + "message_format": "richtext" + } + } +} +``` + +## 2. フィールドリファレンス + +| フィールド | 型 | 必須 | 説明 | +|----------------------|----------|------|------| +| enabled | bool | はい | Matrix チャンネルの有効/無効 | +| homeserver | string | はい | Matrix ホームサーバー URL(例:`https://matrix.org`) | +| user_id | string | はい | ボットの Matrix ユーザー ID(例:`@bot:matrix.org`) | +| access_token | string | はい | ボットのアクセストークン | +| device_id | string | いいえ | オプションの Matrix デバイス ID | +| join_on_invite | bool | いいえ | 招待されたルームに自動参加 | +| allow_from | []string | いいえ | ユーザーホワイトリスト(Matrix ユーザー ID) | +| group_trigger | object | いいえ | グループトリガー戦略(`mention_only` / `prefixes`) | +| placeholder | object | いいえ | プレースホルダーメッセージ設定 | +| reasoning_channel_id | string | いいえ | 推論出力のターゲットチャンネル | +| message_format | string | いいえ | 出力形式:`"richtext"`(デフォルト)は markdown を HTML としてレンダリング;`"plain"` はプレーンテキストのみ送信 | + +## 3. 現在サポートされている機能 + +- markdown レンダリング付きテキストメッセージ送受信(太字、斜体、見出し、コードブロックなど) +- 設定可能なメッセージ形式(`richtext` / `plain`) +- 受信画像/音声/動画/ファイルのダウンロード(MediaStore 優先、ローカルパスフォールバック) +- 受信音声の既存文字起こしフローへの正規化(`[audio: ...]`) +- 送信画像/音声/動画/ファイルのアップロードと送信 +- グループトリガールール(メンションのみモードを含む) +- タイピング状態(`m.typing`) +- プレースホルダーメッセージ + 最終返信の置き換え +- 招待されたルームへの自動参加(無効化可能) + +## 4. TODO + +- リッチメディアメタデータの改善(例:画像/動画のサイズとサムネイル) diff --git a/docs/channels/matrix/README.md b/docs/channels/matrix/README.md index 233f5c0a32..2ed19245a2 100644 --- a/docs/channels/matrix/README.md +++ b/docs/channels/matrix/README.md @@ -1,3 +1,5 @@ +> Back to [README](../../../README.md) + # Matrix Channel Configuration Guide ## 1. Example Configuration diff --git a/docs/channels/matrix/README.pt-br.md b/docs/channels/matrix/README.pt-br.md new file mode 100644 index 0000000000..11a9aaa113 --- /dev/null +++ b/docs/channels/matrix/README.pt-br.md @@ -0,0 +1,64 @@ +> Voltar ao [README](../../../README.pt-br.md) + +# Guia de Configuração do Canal Matrix + +## 1. Exemplo de Configuração + +Adicione isto ao `config.json`: + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "user_id": "@your-bot:matrix.org", + "access_token": "YOUR_MATRIX_ACCESS_TOKEN", + "device_id": "", + "join_on_invite": true, + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "placeholder": { + "enabled": true, + "text": "Thinking..." + }, + "reasoning_channel_id": "", + "message_format": "richtext" + } + } +} +``` + +## 2. Referência de Campos + +| Campo | Tipo | Obrigatório | Descrição | +|----------------------|----------|-------------|-----------| +| enabled | bool | Sim | Habilitar ou desabilitar o canal Matrix | +| homeserver | string | Sim | URL do homeserver Matrix (por exemplo `https://matrix.org`) | +| user_id | string | Sim | ID de usuário Matrix do bot (por exemplo `@bot:matrix.org`) | +| access_token | string | Sim | Token de acesso do bot | +| device_id | string | Não | ID de dispositivo Matrix opcional | +| join_on_invite | bool | Não | Entrar automaticamente em salas convidadas | +| allow_from | []string | Não | Lista branca de usuários (IDs Matrix) | +| group_trigger | object | Não | Estratégia de gatilho de grupo (`mention_only` / `prefixes`) | +| placeholder | object | Não | Configuração de mensagem de espaço reservado | +| reasoning_channel_id | string | Não | Canal alvo para saída de raciocínio | +| message_format | string | Não | Formato de saída: `"richtext"` (padrão) renderiza markdown como HTML; `"plain"` envia apenas texto simples | + +## 3. Suporte Atual + +- Envio/recebimento de mensagens de texto com renderização markdown (negrito, itálico, cabeçalhos, blocos de código, etc.) +- Formato de mensagem configurável (`richtext` / `plain`) +- Download de imagens/áudio/vídeo/arquivos recebidos (MediaStore primeiro, fallback para caminho local) +- Normalização de áudio recebido no fluxo de transcrição existente (`[audio: ...]`) +- Upload e envio de imagens/áudio/vídeo/arquivos de saída +- Regras de gatilho de grupo (incluindo modo somente menção) +- Estado de digitação (`m.typing`) +- Mensagem de espaço reservado + substituição de resposta final +- Entrada automática em salas convidadas (pode ser desabilitado) + +## 4. TODO + +- Melhorias nos metadados de mídia rica (por exemplo tamanho e miniaturas de imagens/vídeos) diff --git a/docs/channels/matrix/README.vi.md b/docs/channels/matrix/README.vi.md new file mode 100644 index 0000000000..f1272076f2 --- /dev/null +++ b/docs/channels/matrix/README.vi.md @@ -0,0 +1,64 @@ +> Quay lại [README](../../../README.vi.md) + +# Hướng dẫn Cấu hình Kênh Matrix + +## 1. Cấu hình Mẫu + +Thêm vào `config.json`: + +```json +{ + "channels": { + "matrix": { + "enabled": true, + "homeserver": "https://matrix.org", + "user_id": "@your-bot:matrix.org", + "access_token": "YOUR_MATRIX_ACCESS_TOKEN", + "device_id": "", + "join_on_invite": true, + "allow_from": [], + "group_trigger": { + "mention_only": true + }, + "placeholder": { + "enabled": true, + "text": "Thinking..." + }, + "reasoning_channel_id": "", + "message_format": "richtext" + } + } +} +``` + +## 2. Tham chiếu Trường + +| Trường | Kiểu | Bắt buộc | Mô tả | +|----------------------|----------|----------|-------| +| enabled | bool | Có | Bật hoặc tắt kênh Matrix | +| homeserver | string | Có | URL homeserver Matrix (ví dụ `https://matrix.org`) | +| user_id | string | Có | ID người dùng Matrix của bot (ví dụ `@bot:matrix.org`) | +| access_token | string | Có | Token truy cập của bot | +| device_id | string | Không | ID thiết bị Matrix tùy chọn | +| join_on_invite | bool | Không | Tự động tham gia phòng được mời | +| allow_from | []string | Không | Danh sách trắng người dùng (ID Matrix) | +| group_trigger | object | Không | Chiến lược kích hoạt nhóm (`mention_only` / `prefixes`) | +| placeholder | object | Không | Cấu hình tin nhắn giữ chỗ | +| reasoning_channel_id | string | Không | Kênh đích cho đầu ra suy luận | +| message_format | string | Không | Định dạng đầu ra: `"richtext"` (mặc định) render markdown thành HTML; `"plain"` chỉ gửi văn bản thuần | + +## 3. Tính năng Hiện tại + +- Gửi/nhận tin nhắn văn bản với render markdown (đậm, nghiêng, tiêu đề, khối code, v.v.) +- Định dạng tin nhắn có thể cấu hình (`richtext` / `plain`) +- Tải xuống hình ảnh/âm thanh/video/tệp đến (MediaStore trước, fallback đường dẫn cục bộ) +- Chuẩn hóa âm thanh đến vào luồng phiên âm hiện có (`[audio: ...]`) +- Tải lên và gửi hình ảnh/âm thanh/video/tệp đi +- Quy tắc kích hoạt nhóm (bao gồm chế độ chỉ đề cập) +- Trạng thái đang gõ (`m.typing`) +- Tin nhắn giữ chỗ + thay thế phản hồi cuối cùng +- Tự động tham gia phòng được mời (có thể tắt) + +## 4. TODO + +- Cải thiện metadata phương tiện phong phú (ví dụ kích thước và hình thu nhỏ hình ảnh/video) diff --git a/docs/channels/matrix/README.zh.md b/docs/channels/matrix/README.zh.md index 1f9e5bbe2b..8db3e4383e 100644 --- a/docs/channels/matrix/README.zh.md +++ b/docs/channels/matrix/README.zh.md @@ -1,3 +1,5 @@ +> 返回 [README](../../../README.zh.md) + # Matrix 通道配置指南 ## 1. 配置示例 diff --git a/docs/chat-apps.md b/docs/chat-apps.md index 07297952aa..b0ebc7c542 100644 --- a/docs/chat-apps.md +++ b/docs/chat-apps.md @@ -10,22 +10,23 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, | Channel | Difficulty | Description | Documentation | | -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md) | -| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](../channels/discord/README.md) | +| **Telegram** | ⭐ Easy | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](channels/telegram/README.md) | +| **Discord** | ⭐ Easy | Socket Mode, group/DM support, rich bot ecosystem | [Docs](channels/discord/README.md) | | **WhatsApp** | ⭐ Easy | Native (QR scan) or Bridge URL | [Docs](#whatsapp) | -| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](../channels/weixin/README.md) | -| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](../channels/slack/README.md) | -| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](../channels/matrix/README.md) | -| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](../channels/qq/README.md) | -| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](../channels/dingtalk/README.md) | -| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](../channels/line/README.md) | -| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.md) / [App](../channels/wecom/wecom_app/README.md) / [AI Bot](../channels/wecom/wecom_aibot/README.md) | -| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](../channels/feishu/README.md) | -| **IRC** | ⭐⭐ Medium | Server + TLS configuration | - | -| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](../channels/onebot/README.md) | -| **MaixCam** | ⭐ Easy | Hardware integration channel for Sipeed AI cameras | [Docs](../channels/maixcam/README.md) | +| **Weixin** | ⭐ Easy | Native QR scan (Tencent iLink API) | [Docs](#weixin) | +| **Slack** | ⭐ Easy | **Socket Mode** (no public IP needed), enterprise | [Docs](channels/slack/README.md) | +| **Matrix** | ⭐⭐ Medium | Federated protocol, self-hosting supported | [Docs](channels/matrix/README.md) | +| **QQ** | ⭐⭐ Medium | Official bot API, Chinese community | [Docs](channels/qq/README.md) | +| **DingTalk** | ⭐⭐ Medium | Stream mode (no public IP needed), enterprise | [Docs](channels/dingtalk/README.md) | +| **LINE** | ⭐⭐⭐ Advanced | HTTPS Webhook required | [Docs](channels/line/README.md) | +| **WeCom (企业微信)** | ⭐⭐⭐ Advanced | Group Bot (Webhook), custom App (API), AI Bot | [Bot](channels/wecom/wecom_bot/README.md) / [App](channels/wecom/wecom_app/README.md) / [AI Bot](channels/wecom/wecom_aibot/README.md) | +| **Feishu (飞书)** | ⭐⭐⭐ Advanced | Enterprise collaboration, feature-rich | [Docs](channels/feishu/README.md) | +| **IRC** | ⭐⭐ Medium | Server + TLS configuration | [Docs](#irc) | +| **OneBot** | ⭐⭐ Medium | NapCat/Go-CQHTTP compatible, community ecosystem | [Docs](channels/onebot/README.md) | +| **MaixCam** | ⭐ Easy | Hardware integration channel for Sipeed AI cameras | [Docs](channels/maixcam/README.md) | | **Pico** | ⭐ Easy | Native PicoClaw protocol channel | | +
Telegram (Recommended) @@ -44,7 +45,7 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, "enabled": true, "token": "YOUR_BOT_TOKEN", "allow_from": ["YOUR_USER_ID"], - "use_markdown_v2": false, + "use_markdown_v2": false } } } @@ -70,6 +71,7 @@ You can set use_markdown_v2: true to enable enhanced formatting options. This al
+
Discord @@ -143,6 +145,7 @@ picoclaw gateway
+
WhatsApp (native via whatsmeow) @@ -170,12 +173,14 @@ If `session_store_path` is empty, the session is stored in `/whatsapp
+
Weixin (WeChat Personal) PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API. **1. Login** + Run the interactive QR login flow: ```bash picoclaw onboard weixin @@ -183,6 +188,7 @@ picoclaw onboard weixin Scan the printed QR code with your WeChat mobile app. On success, the token is saved to your config. **2. Configure** + (Optional) Update `allow_from` with your WeChat User ID to restrict who can message the bot: ```json { @@ -203,6 +209,7 @@ picoclaw gateway
+
QQ @@ -244,6 +251,7 @@ If you prefer to create the bot manually:
+
DingTalk @@ -277,6 +285,7 @@ picoclaw gateway ```
+
Matrix @@ -311,6 +320,7 @@ For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`,
+
LINE @@ -359,6 +369,7 @@ picoclaw gateway
+
WeCom (企业微信) @@ -473,6 +484,7 @@ picoclaw gateway
+
Feishu (Lark) @@ -514,6 +526,7 @@ For full options, see [Feishu Channel Configuration Guide](channels/feishu/READM
+
Slack @@ -547,6 +560,7 @@ picoclaw gateway
+
IRC @@ -580,6 +594,7 @@ The bot will connect to the IRC server and join the specified channels.
+
OneBot (QQ via OneBot protocol) diff --git a/docs/configuration.md b/docs/configuration.md index b5d652a850..56c3e2dc7f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -347,3 +347,396 @@ For long-running tasks (web search, API calls), use the `spawn` tool to create a ```markdown # Periodic Tasks + +## Quick Tasks (respond directly) + +- Report current time + +## Long Tasks (use spawn for async) + +- Search the web for AI news and summarize +- Check email and report important messages +``` + +**Key behaviors:** + +| Feature | Description | +| ----------------------- | --------------------------------------------------------- | +| **spawn** | Creates async subagent, doesn't block heartbeat | +| **Independent context** | Subagent has its own context, no session history | +| **message tool** | Subagent communicates with user directly via message tool | +| **Non-blocking** | After spawning, heartbeat continues to next task | + +#### How Subagent Communication Works + +``` +Heartbeat triggers + ↓ +Agent reads HEARTBEAT.md + ↓ +For long task: spawn subagent + ↓ ↓ +Continue to next task Subagent works independently + ↓ ↓ +All tasks done Subagent uses "message" tool + ↓ ↓ +Respond HEARTBEAT_OK User receives result directly +``` + +The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent. + +**Configuration:** + +```json +{ + "heartbeat": { + "enabled": true, + "interval": 30 + } +} +``` + +| Option | Default | Description | +| ---------- | ------- | ---------------------------------- | +| `enabled` | `true` | Enable/disable heartbeat | +| `interval` | `30` | Check interval in minutes (min: 5) | + +**Environment variables:** + +* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable +* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval + +### Providers + +> [!NOTE] +> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level. + +| Provider | Purpose | Get API Key | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) | + +### Model Configuration (model_list) + +> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers — **zero code changes required!** + +This design also enables **multi-agent support** with flexible provider selection: + +- **Different agents, different providers**: Each agent can use its own LLM provider +- **Model fallbacks**: Configure primary and fallback models for resilience +- **Load balancing**: Distribute requests across multiple endpoints +- **Centralized configuration**: Manage all providers in one place + +#### All Supported Vendors + +| Vendor | `model` Prefix | Default API Base | Protocol | API Key | +| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) | +| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) | +| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) | +| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key | +| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | +| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) | +| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — | +| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) | +| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) | +| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) | +| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only | +| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — | + +#### Basic Configuration + +```json +{ + "model_list": [ + { + "model_name": "ark-code-latest", + "model": "volcengine/ark-code-latest", + "api_key": "sk-your-api-key" + }, + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-openai-key" + }, + { + "model_name": "claude-sonnet-4.6", + "model": "anthropic/claude-sonnet-4.6", + "api_key": "sk-ant-your-key" + }, + { + "model_name": "glm-4.7", + "model": "zhipu/glm-4.7", + "api_key": "your-zhipu-key" + } + ], + "agents": { + "defaults": { + "model": "gpt-5.4" + } + } +} +``` + +#### Vendor-Specific Examples + +
+OpenAI + +```json +{ + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-..." +} +``` + +
+ +
+VolcEngine (Doubao) + +```json +{ + "model_name": "ark-code-latest", + "model": "volcengine/ark-code-latest", + "api_key": "sk-..." +} +``` + +
+ +
+智谱 AI (GLM) + +```json +{ + "model_name": "glm-4.7", + "model": "zhipu/glm-4.7", + "api_key": "your-key" +} +``` + +
+ +
+DeepSeek + +```json +{ + "model_name": "deepseek-chat", + "model": "deepseek/deepseek-chat", + "api_key": "sk-..." +} +``` + +
+ +
+Anthropic + +```json +{ + "model_name": "claude-sonnet-4.6", + "model": "anthropic/claude-sonnet-4.6", + "api_key": "sk-ant-your-key" +} +``` + +> Run `picoclaw auth login --provider anthropic` to paste your API token. + +For direct Anthropic API access or custom endpoints that only support Anthropic's native message format: + +```json +{ + "model_name": "claude-opus-4-6", + "model": "anthropic-messages/claude-opus-4-6", + "api_key": "sk-ant-your-key", + "api_base": "https://api.anthropic.com" +} +``` + +> Use `anthropic-messages` when the endpoint requires Anthropic's native `/v1/messages` format instead of OpenAI-compatible `/v1/chat/completions`. + +
+ +
+Ollama (local) + +```json +{ + "model_name": "llama3", + "model": "ollama/llama3" +} +``` + +
+ +
+Custom Proxy / LiteLLM + +```json +{ + "model_name": "my-custom-model", + "model": "openai/custom-model", + "api_base": "https://my-proxy.com/v1", + "api_key": "sk-..." +} +``` + +PicoClaw strips only the outer `litellm/` prefix before sending the request, so `litellm/lite-gpt4` sends `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`. + +
+ +#### Load Balancing + +Configure multiple endpoints for the same model name — PicoClaw will automatically round-robin between them: + +```json +{ + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_base": "https://api1.example.com/v1", + "api_key": "sk-key1" + }, + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_base": "https://api2.example.com/v1", + "api_key": "sk-key2" + } + ] +} +``` + +#### Migration from Legacy `providers` Config + +The old `providers` configuration is **deprecated** but still supported for backward compatibility. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide. + +### Provider Architecture + +PicoClaw routes providers by protocol family: + +- **OpenAI-compatible**: OpenRouter, Groq, Zhipu, vLLM-style endpoints, and most others. +- **Anthropic**: Claude-native API behavior. +- **Codex/OAuth**: OpenAI OAuth/token authentication route. + +This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`). + +
+Zhipu (legacy providers format) + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model": "glm-4.7", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "providers": { + "zhipu": { + "api_key": "Your API Key", + "api_base": "https://open.bigmodel.cn/api/paas/v4" + } + } +} +``` + +
+ +
+Full config example + +```json +{ + "agents": { + "defaults": { + "model": "anthropic/claude-opus-4-5" + } + }, + "session": { + "dm_scope": "per-channel-peer", + "backlog_limit": 20 + }, + "providers": { + "openrouter": { + "api_key": "sk-or-v1-xxx" + }, + "groq": { + "api_key": "gsk_xxx" + } + }, + "channels": { + "telegram": { + "enabled": true, + "token": "123456:ABC...", + "allow_from": ["123456789"] + } + }, + "tools": { + "web": { + "duckduckgo": { + "enabled": true, + "max_results": 5 + } + } + }, + "heartbeat": { + "enabled": true, + "interval": 30 + } +} +``` + +
+ +### Scheduled Tasks / Reminders + +PicoClaw supports cron-style scheduled tasks via the `cron` tool. The agent can set, list, and cancel reminders or recurring jobs that trigger at specified times. + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} +``` + +Scheduled tasks persist across restarts and are stored in `~/.picoclaw/workspace/cron/`. + +### Advanced Topics + +| Topic | Description | +| ----- | ----------- | +| [Hook System](hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks | +| [Steering](steering.md) | Inject messages into a running agent loop between tool calls | +| [SubTurn](subturn.md) | Subagent coordination, concurrency control, lifecycle | +| [Context Management](agent-refactor/context.md) | Context boundary detection, proactive budget check, compression | diff --git a/docs/fr/chat-apps.md b/docs/fr/chat-apps.md index 67422e0ec4..daff951f41 100644 --- a/docs/fr/chat-apps.md +++ b/docs/fr/chat-apps.md @@ -13,6 +13,7 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din | **Telegram** | ⭐ Facile | Recommandé, transcription vocale, long polling (pas d'IP publique requise) | [Documentation](../channels/telegram/README.fr.md) | | **Discord** | ⭐ Facile | Socket Mode, groupes/DM, écosystème bot riche | [Documentation](../channels/discord/README.fr.md) | | **WhatsApp** | ⭐ Facile | Natif (scan QR) ou Bridge URL | [Documentation](#whatsapp) | +| **Weixin** | ⭐ Facile | Scan QR natif (API Tencent iLink) | [Documentation](#weixin) | | **Slack** | ⭐ Facile | **Socket Mode** (pas d'IP publique requise), entreprise | [Documentation](../channels/slack/README.fr.md) | | **Matrix** | ⭐⭐ Moyen | Protocole fédéré, auto-hébergement possible | [Documentation](../channels/matrix/README.fr.md) | | **QQ** | ⭐⭐ Moyen | API bot officielle, communauté chinoise | [Documentation](../channels/qq/README.fr.md) | @@ -20,11 +21,12 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din | **LINE** | ⭐⭐⭐ Avancé | HTTPS Webhook requis | [Documentation](../channels/line/README.fr.md) | | **WeCom (企业微信)** | ⭐⭐⭐ Avancé | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) | | **Feishu (飞书)** | ⭐⭐⭐ Avancé | Collaboration entreprise, fonctionnalités riches | [Documentation](../channels/feishu/README.fr.md) | -| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | - | +| **IRC** | ⭐⭐ Moyen | Serveur + configuration TLS | [Documentation](#irc) | | **OneBot** | ⭐⭐ Moyen | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md) | | **MaixCam** | ⭐ Facile | Canal d'intégration matérielle pour caméras AI Sipeed | [Documentation](../channels/maixcam/README.fr.md) | | **Pico** | ⭐ Facile | Canal protocole natif PicoClaw | | +
Telegram (Recommandé) @@ -65,6 +67,7 @@ Si l'enregistrement des commandes échoue (erreurs transitoires réseau/API), le
+
Discord @@ -138,6 +141,7 @@ picoclaw gateway
+
WhatsApp (natif via whatsmeow) @@ -165,6 +169,43 @@ Si `session_store_path` est vide, la session est stockée dans `/what
+ +
+Weixin (WeChat Personnel) + +PicoClaw prend en charge la connexion à votre compte WeChat personnel via l'API officielle Tencent iLink. + +**1. Connexion** + +Lancez le flux de connexion interactif par QR code : +```bash +picoclaw onboard weixin +``` +Scannez le QR code affiché avec votre application WeChat mobile. Une fois connecté, le token est sauvegardé dans votre configuration. + +**2. Configurer** + +(Optionnel) Ajoutez votre identifiant utilisateur WeChat dans `allow_from` pour restreindre qui peut envoyer des messages au bot : +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**3. Lancer** +```bash +picoclaw gateway +``` + +
+ +
QQ @@ -206,6 +247,7 @@ Si vous préférez créer le bot manuellement :
+
DingTalk @@ -239,6 +281,7 @@ picoclaw gateway ```
+
Matrix @@ -273,6 +316,7 @@ Pour toutes les options (`device_id`, `join_on_invite`, `group_trigger`, `placeh
+
LINE @@ -321,6 +365,7 @@ picoclaw gateway
+
WeCom (企业微信) @@ -435,6 +480,7 @@ picoclaw gateway
+
Feishu (飞书) @@ -476,6 +522,7 @@ Pour toutes les options, voir le [Guide de Configuration du Canal Feishu](../cha
+
Slack @@ -509,6 +556,7 @@ picoclaw gateway
+
IRC @@ -542,6 +590,7 @@ Le bot se connectera au serveur IRC et rejoindra les canaux spécifiés.
+
OneBot (QQ via protocole OneBot) @@ -580,6 +629,7 @@ picoclaw gateway
+
MaixCam diff --git a/docs/fr/configuration.md b/docs/fr/configuration.md index d56da2cade..8d94620bab 100644 --- a/docs/fr/configuration.md +++ b/docs/fr/configuration.md @@ -214,5 +214,150 @@ L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera toute Pour les tâches longues (recherche web, appels API), utilisez l'outil `spawn` pour créer un **subagent** : ```markdown -# Periodic Tasks +# Tâches Périodiques + +## Tâches Rapides (répondre directement) + +- Indiquer l'heure actuelle + +## Tâches Longues (utiliser spawn pour l'asynchrone) + +- Rechercher les actualités IA sur le web et résumer +- Vérifier les e-mails et signaler les messages importants +``` + +**Comportements clés :** + +| Fonctionnalité | Description | +| ---------------- | ------------------------------------------------------------------ | +| **spawn** | Crée un subagent asynchrone, ne bloque pas le heartbeat | +| **Contexte indépendant** | Le subagent a son propre contexte, sans historique de session | +| **message tool** | Le subagent communique directement avec l'utilisateur | +| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante | + +#### Flux de Communication du Subagent + +``` +Heartbeat déclenché + ↓ +Agent lit HEARTBEAT.md + ↓ +Tâche longue : spawn subagent + ↓ ↓ +Continue tâche suivante Subagent travaille indépendamment + ↓ ↓ +Toutes tâches terminées Subagent utilise "message" tool + ↓ ↓ +Répond HEARTBEAT_OK Utilisateur reçoit le résultat +``` + +**Configuration :** + +```json +{ + "heartbeat": { + "enabled": true, + "interval": 30 + } +} +``` + +| Option | Défaut | Description | +| ---------- | ------ | ---------------------------------------- | +| `enabled` | `true` | Activer/désactiver le heartbeat | +| `interval` | `30` | Intervalle en minutes (minimum : 5) | + +**Variables d'environnement :** + +* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver +* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour changer l'intervalle + +### Providers + +> [!NOTE] +> Groq fournit une transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent. + +| Provider | Usage | Obtenir une clé API | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM (Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM (recommandé, accès à tous modèles) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **Transcription vocale** (Whisper)| [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) | + +### Configuration des Modèles (model_list) + +> **Nouveauté :** PicoClaw utilise désormais une approche **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (ex. `zhipu/glm-4.7`) pour ajouter de nouveaux providers — **aucune modification de code requise !** + +#### Tous les Vendors Supportés + +| Vendor | Préfixe `model` | API Base par défaut | Protocole | API Key | +| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obtenir](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obtenir](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obtenir](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obtenir](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obtenir](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obtenir](https://console.groq.com) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obtenir](https://dashscope.console.aliyun.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (pas de clé) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obtenir](https://openrouter.ai/keys) | +| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement | + +#### Équilibrage de Charge + +Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin : + +```json +{ + "model_list": [ + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" }, + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" } + ] +} +``` + +#### Migration depuis l'ancienne config `providers` + +L'ancienne configuration `providers` est **dépréciée** mais toujours supportée. Voir [docs/migration/model-list-migration.md](../migration/model-list-migration.md). + +### Architecture des Providers + +PicoClaw route les providers par famille de protocole : + +- **Compatible OpenAI** : OpenRouter, Groq, Zhipu, endpoints vLLM et la plupart des autres. +- **Anthropic** : Comportement natif de l'API Claude. +- **Codex/OAuth** : Route d'authentification OAuth/token OpenAI. + +### Tâches Planifiées / Rappels + +PicoClaw supporte les tâches planifiées via l'outil `cron`. L'agent peut définir, lister et annuler des rappels ou tâches récurrentes. + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} ``` + +Les tâches planifiées persistent après redémarrage dans `~/.picoclaw/workspace/cron/`. + +### Sujets Avancés + +| Sujet | Description | +| ----- | ----------- | +| [Système de Hooks](../hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation | +| [Steering](../steering.md) | Injecter des messages dans une boucle agent en cours d'exécution | +| [SubTurn](../subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie | +| [Gestion du Contexte](../agent-refactor/context.md) | Détection des limites de contexte, compression | diff --git a/docs/fr/tools_configuration.md b/docs/fr/tools_configuration.md index f6e1c03745..a0e03a936d 100644 --- a/docs/fr/tools_configuration.md +++ b/docs/fr/tools_configuration.md @@ -41,14 +41,6 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa | `fetch_limit_bytes` | int | 10485760 | Taille maximale du contenu de la page web à récupérer, en octets (par défaut 10 Mo). | | `format` | string | "plaintext" | Format de sortie du contenu récupéré. Options : `plaintext` ou `markdown` (recommandé). | -### Brave - -| Config | Type | Par défaut | Description | -|---------------|--------|------------|---------------------------| -| `enabled` | bool | false | Activer la recherche Brave | -| `api_key` | string | - | Clé API Brave Search | -| `max_results` | int | 5 | Nombre maximum de résultats | - ### DuckDuckGo | Config | Type | Par défaut | Description | @@ -56,6 +48,29 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa | `enabled` | bool | true | Activer la recherche DuckDuckGo | | `max_results` | int | 5 | Nombre maximum de résultats | +### Baidu Search + +| Config | Type | Par défaut | Description | +|---------------|--------|-----------------------------------------------------------------|------------------------------------| +| `enabled` | bool | false | Activer la recherche Baidu | +| `api_key` | string | - | Clé API Qianfan | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL de l'API Baidu Search | +| `max_results` | int | 10 | Nombre maximum de résultats | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + ### Perplexity | Config | Type | Par défaut | Description | @@ -64,6 +79,41 @@ Paramètres généraux pour la récupération et le traitement du contenu des pa | `api_key` | string | - | Clé API Perplexity | | `max_results` | int | 5 | Nombre maximum de résultats | +### Brave + +| Config | Type | Par défaut | Description | +|---------------|--------|------------|---------------------------| +| `enabled` | bool | false | Activer la recherche Brave | +| `api_key` | string | - | Clé API Brave Search | +| `max_results` | int | 5 | Nombre maximum de résultats | + +### Tavily + +| Config | Type | Par défaut | Description | +|---------------|--------|------------|------------------------------------| +| `enabled` | bool | false | Activer la recherche Tavily | +| `api_key` | string | - | Clé API Tavily | +| `base_url` | string | - | URL de base Tavily personnalisée | +| `max_results` | int | 0 | Nombre maximum de résultats (0 = défaut) | + +### SearXNG + +| Config | Type | Par défaut | Description | +|---------------|--------|--------------------------|--------------------------------| +| `enabled` | bool | false | Activer la recherche SearXNG | +| `base_url` | string | `http://localhost:8888` | URL de l'instance SearXNG | +| `max_results` | int | 5 | Nombre maximum de résultats | + +### GLM Search + +| Config | Type | Par défaut | Description | +|-----------------|--------|------------------------------------------------------|---------------------------| +| `enabled` | bool | false | Activer GLM Search | +| `api_key` | string | - | Clé API GLM | +| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL de l'API GLM Search | +| `search_engine` | string | `search_std` | Type de moteur de recherche | +| `max_results` | int | 5 | Nombre maximum de résultats | + ## Outil Exec L'outil exec est utilisé pour exécuter des commandes shell. diff --git a/docs/ja/chat-apps.md b/docs/ja/chat-apps.md index 997a064ff4..789c0125f9 100644 --- a/docs/ja/chat-apps.md +++ b/docs/ja/chat-apps.md @@ -15,6 +15,7 @@ PicoClaw は複数のチャットプラットフォームをサポートして | **Telegram** | ⭐ 簡単 | 推奨、音声テキスト変換対応、ロングポーリング(公開 IP 不要) | [ドキュメント](../channels/telegram/README.ja.md) | | **Discord** | ⭐ 簡単 | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md) | | **WhatsApp** | ⭐ 簡単 | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp) | +| **微信 (Weixin)** | ⭐ 簡単 | ネイティブ QR スキャン(Tencent iLink API)| [ドキュメント](#weixin) | | **Slack** | ⭐ 簡単 | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md) | | **Matrix** | ⭐⭐ 中程度 | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md) | | **QQ** | ⭐⭐ 中程度 | 公式ボット API、中国コミュニティ向け | [ドキュメント](../channels/qq/README.ja.md) | @@ -22,13 +23,14 @@ PicoClaw は複数のチャットプラットフォームをサポートして | **LINE** | ⭐⭐⭐ やや難 | HTTPS Webhook が必要 | [ドキュメント](../channels/line/README.ja.md) | | **WeCom (企業微信)** | ⭐⭐⭐ やや難 | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) | | **Feishu (飛書)** | ⭐⭐⭐ やや難 | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md) | -| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | - | +| **IRC** | ⭐⭐ 中程度 | サーバー + TLS 設定 | [ドキュメント](#irc) | | **OneBot** | ⭐⭐ 中程度 | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md) | | **MaixCam** | ⭐ 簡単 | Sipeed AI カメラハードウェア統合チャネル | [ドキュメント](../channels/maixcam/README.ja.md) | | **Pico** | ⭐ 簡単 | PicoClaw ネイティブプロトコルチャネル | | --- +
Telegram(推奨) @@ -69,6 +71,7 @@ Telegram 側はコマンドメニュー登録機能を保持し、汎用コマ
+
Discord @@ -143,6 +146,7 @@ picoclaw gateway
+
WhatsApp(ネイティブ whatsmeow) @@ -170,6 +174,43 @@ PicoClaw は 2 つの WhatsApp 接続方式をサポートしています:
+ +
+微信 (Weixin) + +PicoClaw は Tencent iLink 公式 API を使用して WeChat 個人アカウントへの接続をサポートしています。 + +**1. ログイン** + +インタラクティブな QR ログインフローを実行します: +```bash +picoclaw onboard weixin +``` +WeChat モバイルアプリで表示された QR コードをスキャンしてください。ログイン成功後、トークンが設定ファイルに保存されます。 + +**2. 設定** + +(オプション)ボットと会話できるユーザーを制限するために `allow_from` に WeChat ユーザー ID を追加します: +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**3. 実行** +```bash +picoclaw gateway +``` + +
+ +
Matrix @@ -204,6 +245,7 @@ picoclaw gateway
+
QQ @@ -245,6 +287,7 @@ QQ 開放プラットフォームでは、OpenClaw 互換ボットのワンク
+
Slack @@ -278,6 +321,7 @@ picoclaw gateway
+
IRC @@ -311,6 +355,7 @@ picoclaw gateway
+
DingTalk @@ -345,6 +390,7 @@ picoclaw gateway
+
LINE @@ -393,6 +439,7 @@ picoclaw gateway
+
Feishu (飛書) @@ -434,6 +481,7 @@ picoclaw gateway
+
WeCom (企業微信) @@ -548,6 +596,7 @@ picoclaw gateway
+
OneBot(OneBot プロトコル経由の QQ) @@ -586,6 +635,7 @@ picoclaw gateway
+
MaixCam diff --git a/docs/ja/configuration.md b/docs/ja/configuration.md index 215b35d54d..35676809ee 100644 --- a/docs/ja/configuration.md +++ b/docs/ja/configuration.md @@ -256,3 +256,109 @@ Agent は 30 分ごと(設定可能)にこのファイルを読み取り、 - `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化 - `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔を変更 + +#### サブ Agent の通信フロー + +``` +ハートビート起動 + ↓ +Agent が HEARTBEAT.md を読む + ↓ +長時間タスク:spawn サブ Agent + ↓ ↓ +次のタスクへ継続 サブ Agent が独立して動作 + ↓ ↓ +全タスク完了 サブ Agent が "message" ツールを使用 + ↓ ↓ +HEARTBEAT_OK を返信 ユーザーが直接結果を受信 +``` + +### Providers + +> [!NOTE] +> Groq は Whisper による無料音声文字起こしを提供します。設定すると、任意のチャンネルの音声メッセージが Agent レベルで自動的に文字起こしされます。 + +| Provider | 用途 | API キー取得 | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM(Gemini 直接) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM(Zhipu 直接) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM(Volcengine 直接) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM(推奨、全モデルにアクセス可能) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM(Claude 直接) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM(GPT 直接) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM(DeepSeek 直接) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM(Qwen 直接) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **音声文字起こし**(Whisper) | [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM(Cerebras 直接) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM(Vivgrid 直接) | [vivgrid.com](https://vivgrid.com) | + +### モデル設定 (model_list) + +> **新機能:** PicoClaw は**モデル中心**の設定アプローチを採用しました。`vendor/model` 形式(例:`zhipu/glm-4.7`)を指定するだけで新しい Provider を追加できます — **コード変更不要!** + +#### サポートされている全 Vendor + +| Vendor | `model` プレフィックス | デフォルト API Base | プロトコル | API Key | +| ----------------------- | ---------------------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [取得](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [取得](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [取得](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [取得](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [取得](https://console.groq.com) | +| **通義千問 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [取得](https://dashscope.console.aliyun.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | ローカル(キー不要) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [取得](https://openrouter.ai/keys) | +| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [取得](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth のみ | + +#### ロードバランシング + +同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンします: + +```json +{ + "model_list": [ + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" }, + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" } + ] +} +``` + +#### 旧 `providers` 設定からの移行 + +旧 `providers` 設定は**非推奨**ですが後方互換性のためサポートされています。[docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。 + +### Provider アーキテクチャ + +PicoClaw はプロトコルファミリーで Provider をルーティングします: + +- **OpenAI 互換**:OpenRouter、Groq、Zhipu、vLLM スタイルのエンドポイントなど。 +- **Anthropic**:Claude ネイティブ API の動作。 +- **Codex/OAuth**:OpenAI OAuth/トークン認証ルート。 + +### スケジュールタスク / リマインダー + +PicoClaw は `cron` ツールを通じて cron スタイルのスケジュールタスクをサポートします。 + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} +``` + +スケジュールタスクは再起動後も `~/.picoclaw/workspace/cron/` に保存されます。 + +### 高度なトピック + +| トピック | 説明 | +| -------- | ---- | +| [Hook システム](../hooks/README.md) | イベント駆動 Hook:オブザーバー、インターセプター、承認 Hook | +| [Steering](../steering.md) | 実行中の Agent ループにメッセージを注入 | +| [SubTurn](../subturn.md) | サブ Agent の調整、並行制御、ライフサイクル | +| [コンテキスト管理](../agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 | diff --git a/docs/ja/tools_configuration.md b/docs/ja/tools_configuration.md index c40e585389..9b95d33e3e 100644 --- a/docs/ja/tools_configuration.md +++ b/docs/ja/tools_configuration.md @@ -41,14 +41,6 @@ Web ツールはウェブ検索とフェッチに使用されます。 | `fetch_limit_bytes` | int | 10485760 | 取得するウェブページペイロードの最大サイズ(バイト単位、デフォルトは10MB)。 | | `format` | string | "plaintext" | 取得コンテンツの出力形式。オプション:`plaintext` または `markdown`(推奨)。 | -### Brave - -| 設定項目 | 型 | デフォルト | 説明 | -|---------------|--------|------------|-----------------------| -| `enabled` | bool | false | Brave 検索を有効にする | -| `api_key` | string | - | Brave Search API キー | -| `max_results` | int | 5 | 最大結果数 | - ### DuckDuckGo | 設定項目 | 型 | デフォルト | 説明 | @@ -56,6 +48,29 @@ Web ツールはウェブ検索とフェッチに使用されます。 | `enabled` | bool | true | DuckDuckGo 検索を有効にする | | `max_results` | int | 5 | 最大結果数 | +### Baidu Search + +| 設定項目 | 型 | デフォルト | 説明 | +|---------------|--------|-----------------------------------------------------------------|-------------------------------| +| `enabled` | bool | false | Baidu 検索を有効にする | +| `api_key` | string | - | Qianfan API キー | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL | +| `max_results` | int | 10 | 最大結果数 | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + ### Perplexity | 設定項目 | 型 | デフォルト | 説明 | @@ -64,6 +79,41 @@ Web ツールはウェブ検索とフェッチに使用されます。 | `api_key` | string | - | Perplexity API キー | | `max_results` | int | 5 | 最大結果数 | +### Brave + +| 設定項目 | 型 | デフォルト | 説明 | +|---------------|--------|------------|-----------------------| +| `enabled` | bool | false | Brave 検索を有効にする | +| `api_key` | string | - | Brave Search API キー | +| `max_results` | int | 5 | 最大結果数 | + +### Tavily + +| 設定項目 | 型 | デフォルト | 説明 | +|---------------|--------|------------|-----------------------------------| +| `enabled` | bool | false | Tavily 検索を有効にする | +| `api_key` | string | - | Tavily API キー | +| `base_url` | string | - | カスタム Tavily API ベース URL | +| `max_results` | int | 0 | 最大結果数(0 = デフォルト) | + +### SearXNG + +| 設定項目 | 型 | デフォルト | 説明 | +|---------------|--------|--------------------------|---------------------------| +| `enabled` | bool | false | SearXNG 検索を有効にする | +| `base_url` | string | `http://localhost:8888` | SearXNG インスタンス URL | +| `max_results` | int | 5 | 最大結果数 | + +### GLM Search + +| 設定項目 | 型 | デフォルト | 説明 | +|-----------------|--------|------------------------------------------------------|---------------------------| +| `enabled` | bool | false | GLM Search を有効にする | +| `api_key` | string | - | GLM API キー | +| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL | +| `search_engine` | string | `search_std` | 検索エンジンタイプ | +| `max_results` | int | 5 | 最大結果数 | + ## Exec ツール Exec ツールはシェルコマンドの実行に使用されます。 diff --git a/docs/pt-br/chat-apps.md b/docs/pt-br/chat-apps.md index 08ef292fa2..4fa59b1b22 100644 --- a/docs/pt-br/chat-apps.md +++ b/docs/pt-br/chat-apps.md @@ -13,6 +13,7 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D | **Telegram** | ⭐ Fácil | Recomendado, voz para texto, long polling (sem IP público) | [Documentação](../channels/telegram/README.pt-br.md) | | **Discord** | ⭐ Fácil | Socket Mode, suporte a grupos/DM, ecossistema bot rico | [Documentação](../channels/discord/README.pt-br.md) | | **WhatsApp** | ⭐ Fácil | Nativo (scan QR) ou Bridge URL | [Documentação](#whatsapp) | +| **Weixin** | ⭐ Fácil | Scan QR nativo (API Tencent iLink) | [Documentação](#weixin) | | **Slack** | ⭐ Fácil | **Socket Mode** (sem IP público), empresarial | [Documentação](../channels/slack/README.pt-br.md) | | **Matrix** | ⭐⭐ Médio | Protocolo federado, suporte a auto-hospedagem | [Documentação](../channels/matrix/README.pt-br.md) | | **QQ** | ⭐⭐ Médio | API bot oficial, comunidade chinesa | [Documentação](../channels/qq/README.pt-br.md) | @@ -20,11 +21,12 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D | **LINE** | ⭐⭐⭐ Avançado | HTTPS Webhook obrigatório | [Documentação](../channels/line/README.pt-br.md) | | **WeCom (企业微信)** | ⭐⭐⭐ Avançado | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.pt-br.md) / [App](../channels/wecom/wecom_app/README.pt-br.md) / [AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) | | **Feishu (飞书)** | ⭐⭐⭐ Avançado | Colaboração empresarial, rico em recursos | [Documentação](../channels/feishu/README.pt-br.md) | -| **IRC** | ⭐⭐ Médio | Servidor + configuração TLS | - | +| **IRC** | ⭐⭐ Médio | Servidor + configuração TLS | [Documentação](#irc) | | **OneBot** | ⭐⭐ Médio | Compatível com NapCat/Go-CQHTTP, ecossistema comunitário | [Documentação](../channels/onebot/README.pt-br.md) | | **MaixCam** | ⭐ Fácil | Canal de integração de hardware para câmeras AI Sipeed | [Documentação](../channels/maixcam/README.pt-br.md) | | **Pico** | ⭐ Fácil | Canal de protocolo nativo PicoClaw | | +
Telegram (Recomendado) @@ -65,6 +67,7 @@ Se o registro de comandos falhar (erros transitórios de rede/API), o canal aind
+
Discord @@ -138,6 +141,7 @@ picoclaw gateway
+
WhatsApp (nativo via whatsmeow) @@ -165,6 +169,43 @@ Se `session_store_path` estiver vazio, a sessão é armazenada em `/w
+ +
+Weixin (WeChat Pessoal) + +O PicoClaw suporta conexão com sua conta pessoal do WeChat usando a API oficial Tencent iLink. + +**1. Login** + +Execute o fluxo de login interativo por QR code: +```bash +picoclaw onboard weixin +``` +Escaneie o QR code exibido com seu aplicativo WeChat mobile. Após o login bem-sucedido, o token é salvo na sua configuração. + +**2. Configurar** + +(Opcional) Adicione seu ID de usuário WeChat em `allow_from` para restringir quem pode enviar mensagens ao bot: +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**3. Executar** +```bash +picoclaw gateway +``` + +
+ +
QQ @@ -206,6 +247,7 @@ Se preferir criar o bot manualmente:
+
DingTalk @@ -240,6 +282,7 @@ picoclaw gateway
+
MaixCam @@ -262,6 +305,7 @@ picoclaw gateway
+
Matrix @@ -296,6 +340,7 @@ Para opções completas (`device_id`, `join_on_invite`, `group_trigger`, `placeh
+
LINE @@ -344,6 +389,7 @@ picoclaw gateway
+
WeCom (企业微信) @@ -457,6 +503,7 @@ picoclaw gateway
+
Feishu (Lark) @@ -498,6 +545,7 @@ Para opções completas, veja o [Guia de Configuração do Canal Feishu](../chan
+
Slack @@ -531,6 +579,7 @@ picoclaw gateway
+
IRC @@ -564,6 +613,7 @@ O bot se conectará ao servidor IRC e entrará nos canais especificados.
+
OneBot (QQ via protocolo OneBot) diff --git a/docs/pt-br/configuration.md b/docs/pt-br/configuration.md index ee14ca7246..ff3ce2b34f 100644 --- a/docs/pt-br/configuration.md +++ b/docs/pt-br/configuration.md @@ -216,4 +216,149 @@ Para tarefas de longa duração (busca na web, chamadas de API), use a ferrament ```markdown # Tarefas Periódicas + +## Tarefas Rápidas (responder diretamente) + +- Informar a hora atual + +## Tarefas Longas (usar spawn para assíncrono) + +- Pesquisar notícias de IA na web e resumir +- Verificar e-mails e reportar mensagens importantes +``` + +**Comportamentos principais:** + +| Funcionalidade | Descrição | +| ---------------- | ------------------------------------------------------------------ | +| **spawn** | Cria subagente assíncrono, não bloqueia o heartbeat | +| **Contexto independente** | Subagente tem seu próprio contexto, sem histórico de sessão | +| **message tool** | Subagente comunica diretamente com o usuário via message tool | +| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa | + +#### Fluxo de Comunicação do Subagente + +``` +Heartbeat disparado + ↓ +Agent lê HEARTBEAT.md + ↓ +Tarefa longa: spawn subagente + ↓ ↓ +Continua próxima tarefa Subagente trabalha independentemente + ↓ ↓ +Todas tarefas concluídas Subagente usa ferramenta "message" + ↓ ↓ +Responde HEARTBEAT_OK Usuário recebe resultado diretamente +``` + +**Configuração:** + +```json +{ + "heartbeat": { + "enabled": true, + "interval": 30 + } +} ``` + +| Opção | Padrão | Descrição | +| ---------- | ------ | -------------------------------------- | +| `enabled` | `true` | Ativar/desativar heartbeat | +| `interval` | `30` | Intervalo em minutos (mínimo: 5) | + +**Variáveis de ambiente:** + +* `PICOCLAW_HEARTBEAT_ENABLED=false` para desativar +* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo + +### Providers + +> [!NOTE] +> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente. + +| Provider | Finalidade | Obter API Key | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM (Volcengine direto) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM (recomendado, acesso a todos modelos) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM (Qwen direto) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM (Cerebras direto) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM (Vivgrid direto) | [vivgrid.com](https://vivgrid.com) | + +### Configuração de Modelos (model_list) + +> **Novidade:** PicoClaw agora usa uma abordagem **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos providers — **sem alterações de código!** + +#### Todos os Vendors Suportados + +| Vendor | Prefixo `model` | API Base padrão | Protocolo | API Key | +| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obter](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obter](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obter](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obter](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obter](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obter](https://console.groq.com) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obter](https://dashscope.console.aliyun.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (sem chave) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obter](https://openrouter.ai/keys) | +| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obter](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | Somente OAuth | + +#### Balanceamento de Carga + +Configure múltiplos endpoints para o mesmo nome de modelo — PicoClaw fará round-robin automaticamente: + +```json +{ + "model_list": [ + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" }, + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" } + ] +} +``` + +#### Migração da Configuração Legada `providers` + +A configuração antiga `providers` está **depreciada** mas ainda é suportada. Veja [docs/migration/model-list-migration.md](../migration/model-list-migration.md). + +### Arquitetura de Providers + +PicoClaw roteia providers por família de protocolo: + +- **Compatível com OpenAI**: OpenRouter, Groq, Zhipu, endpoints vLLM e a maioria dos outros. +- **Anthropic**: Comportamento nativo da API Claude. +- **Codex/OAuth**: Rota de autenticação OAuth/token OpenAI. + +### Tarefas Agendadas / Lembretes + +PicoClaw suporta tarefas agendadas via ferramenta `cron`. + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} +``` + +As tarefas agendadas persistem após reinicializações em `~/.picoclaw/workspace/cron/`. + +### Tópicos Avançados + +| Tópico | Descrição | +| ------ | --------- | +| [Sistema de Hooks](../hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação | +| [Steering](../steering.md) | Injetar mensagens em um loop de agente em execução | +| [SubTurn](../subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida | +| [Gerenciamento de Contexto](../agent-refactor/context.md) | Detecção de limites de contexto, compressão | diff --git a/docs/pt-br/tools_configuration.md b/docs/pt-br/tools_configuration.md index 2cc4f39992..60f0ace4df 100644 --- a/docs/pt-br/tools_configuration.md +++ b/docs/pt-br/tools_configuration.md @@ -41,14 +41,6 @@ Configurações gerais para busca e processamento de conteúdo de páginas web. | `fetch_limit_bytes` | int | 10485760 | Tamanho máximo do payload da página web a ser buscado, em bytes (padrão é 10MB). | | `format` | string | "plaintext" | Formato de saída do conteúdo buscado. Opções: `plaintext` ou `markdown` (recomendado). | -### Brave - -| Config | Tipo | Padrão | Descrição | -|---------------|--------|--------|----------------------------| -| `enabled` | bool | false | Habilitar pesquisa Brave | -| `api_key` | string | - | Chave API do Brave Search | -| `max_results` | int | 5 | Número máximo de resultados | - ### DuckDuckGo | Config | Tipo | Padrão | Descrição | @@ -56,6 +48,29 @@ Configurações gerais para busca e processamento de conteúdo de páginas web. | `enabled` | bool | true | Habilitar pesquisa DuckDuckGo | | `max_results` | int | 5 | Número máximo de resultados | +### Baidu Search + +| Config | Tipo | Padrão | Descrição | +|---------------|--------|-----------------------------------------------------------------|------------------------------------| +| `enabled` | bool | false | Habilitar pesquisa Baidu | +| `api_key` | string | - | Chave API Qianfan | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL da API Baidu Search | +| `max_results` | int | 10 | Número máximo de resultados | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + ### Perplexity | Config | Tipo | Padrão | Descrição | @@ -64,6 +79,41 @@ Configurações gerais para busca e processamento de conteúdo de páginas web. | `api_key` | string | - | Chave API do Perplexity | | `max_results` | int | 5 | Número máximo de resultados | +### Brave + +| Config | Tipo | Padrão | Descrição | +|---------------|--------|--------|----------------------------| +| `enabled` | bool | false | Habilitar pesquisa Brave | +| `api_key` | string | - | Chave API do Brave Search | +| `max_results` | int | 5 | Número máximo de resultados | + +### Tavily + +| Config | Tipo | Padrão | Descrição | +|---------------|--------|--------|------------------------------------| +| `enabled` | bool | false | Habilitar pesquisa Tavily | +| `api_key` | string | - | Chave API do Tavily | +| `base_url` | string | - | URL base personalizada do Tavily | +| `max_results` | int | 0 | Número máximo de resultados (0 = padrão) | + +### SearXNG + +| Config | Tipo | Padrão | Descrição | +|---------------|--------|--------------------------|--------------------------------| +| `enabled` | bool | false | Habilitar pesquisa SearXNG | +| `base_url` | string | `http://localhost:8888` | URL da instância SearXNG | +| `max_results` | int | 5 | Número máximo de resultados | + +### GLM Search + +| Config | Tipo | Padrão | Descrição | +|-----------------|--------|------------------------------------------------------|----------------------------| +| `enabled` | bool | false | Habilitar GLM Search | +| `api_key` | string | - | Chave API GLM | +| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL da API GLM Search | +| `search_engine` | string | `search_std` | Tipo de motor de busca | +| `max_results` | int | 5 | Número máximo de resultados | + ## Ferramenta Exec A ferramenta exec é usada para executar comandos shell. diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md index d0160050d8..0528fe714f 100644 --- a/docs/tools_configuration.md +++ b/docs/tools_configuration.md @@ -55,6 +55,31 @@ General settings for fetching and processing webpage content. | `enabled` | bool | true | Enable DuckDuckGo search | | `max_results` | int | 5 | Maximum number of results | +### Baidu Search + +Baidu Search uses the [Qianfan AI Search API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5), which is AI-powered and optimized for Chinese-language queries. + +| Config | Type | Default | Description | +|---------------|--------|------------------------------------------------------------------|---------------------------| +| `enabled` | bool | false | Enable Baidu Search | +| `api_key` | string | - | Qianfan API key | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | Baidu Search API URL | +| `max_results` | int | 10 | Maximum number of results | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + ### Perplexity | Config | Type | Default | Description | diff --git a/docs/vi/chat-apps.md b/docs/vi/chat-apps.md index 3680fed691..d907e5e91e 100644 --- a/docs/vi/chat-apps.md +++ b/docs/vi/chat-apps.md @@ -13,6 +13,7 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix | **Telegram** | ⭐ Dễ | Khuyến nghị, chuyển giọng nói thành văn bản, long polling (không cần IP công khai) | [Tài liệu](../channels/telegram/README.vi.md) | | **Discord** | ⭐ Dễ | Socket Mode, hỗ trợ nhóm/DM, hệ sinh thái bot phong phú | [Tài liệu](../channels/discord/README.vi.md) | | **WhatsApp** | ⭐ Dễ | Bản địa (quét QR) hoặc Bridge URL | [Tài liệu](#whatsapp) | +| **Weixin** | ⭐ Dễ | Quét QR gốc (API Tencent iLink) | [Tài liệu](#weixin) | | **Slack** | ⭐ Dễ | **Socket Mode** (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/slack/README.vi.md) | | **Matrix** | ⭐⭐ Trung bình | Giao thức liên kết, hỗ trợ tự lưu trữ | [Tài liệu](../channels/matrix/README.vi.md) | | **QQ** | ⭐⭐ Trung bình | API bot chính thức, cộng đồng Trung Quốc | [Tài liệu](../channels/qq/README.vi.md) | @@ -20,11 +21,12 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix | **LINE** | ⭐⭐⭐ Nâng cao | Yêu cầu HTTPS Webhook | [Tài liệu](../channels/line/README.vi.md) | | **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.vi.md) / [App](../channels/wecom/wecom_app/README.vi.md) / [AI Bot](../channels/wecom/wecom_aibot/README.vi.md) | | **Feishu (飞书)** | ⭐⭐⭐ Nâng cao | Cộng tác doanh nghiệp, nhiều tính năng | [Tài liệu](../channels/feishu/README.vi.md) | -| **IRC** | ⭐⭐ Trung bình | Máy chủ + cấu hình TLS | - | +| **IRC** | ⭐⭐ Trung bình | Máy chủ + cấu hình TLS | [Tài liệu](#irc) | | **OneBot** | ⭐⭐ Trung bình | Tương thích NapCat/Go-CQHTTP, hệ sinh thái cộng đồng | [Tài liệu](../channels/onebot/README.vi.md) | | **MaixCam** | ⭐ Dễ | Kênh tích hợp phần cứng cho camera AI Sipeed | [Tài liệu](../channels/maixcam/README.vi.md) | | **Pico** | ⭐ Dễ | Kênh giao thức bản địa PicoClaw | | +
Telegram (Khuyến nghị) @@ -65,6 +67,7 @@ Nếu đăng ký lệnh thất bại (lỗi tạm thời mạng/API), kênh vẫ
+
Discord @@ -138,6 +141,7 @@ picoclaw gateway
+
WhatsApp (native qua whatsmeow) @@ -165,6 +169,43 @@ Nếu `session_store_path` trống, phiên được lưu tại `/what
+ +
+Weixin (WeChat Cá nhân) + +PicoClaw hỗ trợ kết nối với tài khoản WeChat cá nhân của bạn thông qua API chính thức Tencent iLink. + +**1. Đăng nhập** + +Chạy luồng đăng nhập QR tương tác: +```bash +picoclaw onboard weixin +``` +Quét mã QR được in ra bằng ứng dụng WeChat trên điện thoại. Sau khi đăng nhập thành công, token sẽ được lưu vào cấu hình. + +**2. Cấu hình** + +(Tùy chọn) Thêm ID người dùng WeChat vào `allow_from` để giới hạn ai có thể nhắn tin với bot: +```json +{ + "channels": { + "weixin": { + "enabled": true, + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] + } + } +} +``` + +**3. Chạy** +```bash +picoclaw gateway +``` + +
+ +
QQ @@ -206,6 +247,7 @@ Nếu bạn muốn tạo bot thủ công:
+
DingTalk @@ -240,6 +282,7 @@ picoclaw gateway
+
MaixCam @@ -262,6 +305,7 @@ picoclaw gateway
+
Matrix @@ -296,6 +340,7 @@ picoclaw gateway
+
LINE @@ -344,6 +389,7 @@ picoclaw gateway
+
WeCom (企业微信) @@ -458,6 +504,7 @@ picoclaw gateway
+
Feishu (Lark) @@ -499,6 +546,7 @@ Mở Feishu, tìm tên bot của bạn và bắt đầu trò chuyện. Bạn cũ
+
Slack @@ -532,6 +580,7 @@ picoclaw gateway
+
IRC @@ -565,6 +614,7 @@ Bot sẽ kết nối đến máy chủ IRC và tham gia các kênh đã chỉ đ
+
OneBot (QQ qua giao thức OneBot) diff --git a/docs/vi/configuration.md b/docs/vi/configuration.md index a21929359f..fecadc6ff9 100644 --- a/docs/vi/configuration.md +++ b/docs/vi/configuration.md @@ -216,4 +216,149 @@ Cho tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ ` ```markdown # Tác Vụ Định Kỳ + +## Tác Vụ Nhanh (trả lời trực tiếp) + +- Báo giờ hiện tại + +## Tác Vụ Dài (dùng spawn cho bất đồng bộ) + +- Tìm kiếm tin tức AI trên web và tóm tắt +- Kiểm tra email và báo cáo tin nhắn quan trọng +``` + +**Hành vi chính:** + +| Tính năng | Mô tả | +| ---------------- | ------------------------------------------------------------------ | +| **spawn** | Tạo subagent bất đồng bộ, không chặn heartbeat | +| **Ngữ cảnh độc lập** | Subagent có ngữ cảnh riêng, không có lịch sử phiên | +| **message tool** | Subagent giao tiếp trực tiếp với người dùng qua message tool | +| **Không chặn** | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo | + +#### Luồng Giao Tiếp Của Subagent + +``` +Heartbeat kích hoạt + ↓ +Agent đọc HEARTBEAT.md + ↓ +Tác vụ dài: spawn subagent + ↓ ↓ +Tiếp tục tác vụ tiếp theo Subagent hoạt động độc lập + ↓ ↓ +Hoàn thành tất cả tác vụ Subagent dùng công cụ "message" + ↓ ↓ +Trả lời HEARTBEAT_OK Người dùng nhận kết quả trực tiếp +``` + +**Cấu hình:** + +```json +{ + "heartbeat": { + "enabled": true, + "interval": 30 + } +} ``` + +| Tùy chọn | Mặc định | Mô tả | +| ---------- | -------- | -------------------------------------- | +| `enabled` | `true` | Bật/tắt heartbeat | +| `interval` | `30` | Khoảng thời gian kiểm tra tính bằng phút (tối thiểu: 5) | + +**Biến môi trường:** + +* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt +* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian + +### Providers + +> [!NOTE] +> Groq cung cấp chuyển đổi giọng nói thành văn bản miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp độ agent. + +| Provider | Mục đích | Lấy API Key | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM (Gemini trực tiếp) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM (Zhipu trực tiếp) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM (Volcengine trực tiếp) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM (khuyến nghị, truy cập tất cả mô hình) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM (Claude trực tiếp) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM (GPT trực tiếp) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM (DeepSeek trực tiếp) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM (Qwen trực tiếp) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **Chuyển đổi giọng nói** (Whisper)| [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM (Cerebras trực tiếp) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM (Vivgrid trực tiếp) | [vivgrid.com](https://vivgrid.com) | + +### Cấu Hình Mô Hình (model_list) + +> **Tính năng mới:** PicoClaw hiện sử dụng cách tiếp cận **lấy mô hình làm trung tâm**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!** + +#### Tất Cả Vendor Được Hỗ Trợ + +| Vendor | Tiền tố `model` | API Base mặc định | Giao thức | API Key | +| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Lấy](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Lấy](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Lấy](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Lấy](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Lấy](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Lấy](https://console.groq.com) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Lấy](https://dashscope.console.aliyun.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Cục bộ (không cần key) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Lấy](https://openrouter.ai/keys) | +| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Lấy](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | Chỉ OAuth | + +#### Cân Bằng Tải + +Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin: + +```json +{ + "model_list": [ + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" }, + { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" } + ] +} +``` + +#### Di Chuyển Từ Cấu Hình `providers` Cũ + +Cấu hình `providers` cũ đã **bị deprecated** nhưng vẫn được hỗ trợ. Xem [docs/migration/model-list-migration.md](../migration/model-list-migration.md). + +### Kiến Trúc Provider + +PicoClaw định tuyến provider theo họ giao thức: + +- **Tương thích OpenAI**: OpenRouter, Groq, Zhipu, endpoint kiểu vLLM và hầu hết các provider khác. +- **Anthropic**: Hành vi API Claude gốc. +- **Codex/OAuth**: Tuyến xác thực OAuth/token OpenAI. + +### Tác Vụ Đã Lên Lịch / Nhắc Nhở + +PicoClaw hỗ trợ tác vụ theo lịch qua công cụ `cron`. + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} +``` + +Tác vụ đã lên lịch được lưu trữ bền vững sau khi khởi động lại tại `~/.picoclaw/workspace/cron/`. + +### Chủ Đề Nâng Cao + +| Chủ đề | Mô tả | +| ------ | ----- | +| [Hệ Thống Hook](../hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook | +| [Steering](../steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy | +| [SubTurn](../subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời | +| [Quản Lý Ngữ Cảnh](../agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén | diff --git a/docs/vi/tools_configuration.md b/docs/vi/tools_configuration.md index 76a3361860..737d8118da 100644 --- a/docs/vi/tools_configuration.md +++ b/docs/vi/tools_configuration.md @@ -41,14 +41,6 @@ Cài đặt chung để tải và xử lý nội dung trang web. | `fetch_limit_bytes` | int | 10485760 | Kích thước tối đa của payload trang web cần tải, tính bằng byte (mặc định là 10MB). | | `format` | string | "plaintext" | Định dạng đầu ra của nội dung đã tải. Tùy chọn: `plaintext` hoặc `markdown` (khuyến nghị). | -### Brave - -| Cấu hình | Kiểu | Mặc định | Mô tả | -|----------------|--------|----------|----------------------------| -| `enabled` | bool | false | Bật tìm kiếm Brave | -| `api_key` | string | - | Khóa API Brave Search | -| `max_results` | int | 5 | Số kết quả tối đa | - ### DuckDuckGo | Cấu hình | Kiểu | Mặc định | Mô tả | @@ -56,6 +48,29 @@ Cài đặt chung để tải và xử lý nội dung trang web. | `enabled` | bool | true | Bật tìm kiếm DuckDuckGo | | `max_results` | int | 5 | Số kết quả tối đa | +### Baidu Search + +| Cấu hình | Kiểu | Mặc định | Mô tả | +|----------------|--------|-----------------------------------------------------------------|------------------------------------| +| `enabled` | bool | false | Bật tìm kiếm Baidu | +| `api_key` | string | - | Khóa API Qianfan | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | URL API Baidu Search | +| `max_results` | int | 10 | Số kết quả tối đa | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + ### Perplexity | Cấu hình | Kiểu | Mặc định | Mô tả | @@ -64,6 +79,41 @@ Cài đặt chung để tải và xử lý nội dung trang web. | `api_key` | string | - | Khóa API Perplexity | | `max_results` | int | 5 | Số kết quả tối đa | +### Brave + +| Cấu hình | Kiểu | Mặc định | Mô tả | +|----------------|--------|----------|----------------------------| +| `enabled` | bool | false | Bật tìm kiếm Brave | +| `api_key` | string | - | Khóa API Brave Search | +| `max_results` | int | 5 | Số kết quả tối đa | + +### Tavily + +| Cấu hình | Kiểu | Mặc định | Mô tả | +|----------------|--------|----------|------------------------------------| +| `enabled` | bool | false | Bật tìm kiếm Tavily | +| `api_key` | string | - | Khóa API Tavily | +| `base_url` | string | - | URL cơ sở Tavily tùy chỉnh | +| `max_results` | int | 0 | Số kết quả tối đa (0 = mặc định) | + +### SearXNG + +| Cấu hình | Kiểu | Mặc định | Mô tả | +|----------------|--------|--------------------------|----------------------------| +| `enabled` | bool | false | Bật tìm kiếm SearXNG | +| `base_url` | string | `http://localhost:8888` | URL phiên bản SearXNG | +| `max_results` | int | 5 | Số kết quả tối đa | + +### GLM Search + +| Cấu hình | Kiểu | Mặc định | Mô tả | +|------------------|--------|------------------------------------------------------|----------------------------| +| `enabled` | bool | false | Bật GLM Search | +| `api_key` | string | - | Khóa API GLM | +| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | URL API GLM Search | +| `search_engine` | string | `search_std` | Loại công cụ tìm kiếm | +| `max_results` | int | 5 | Số kết quả tối đa | + ## Công cụ Exec Công cụ exec được sử dụng để thực thi các lệnh shell. diff --git a/docs/zh/chat-apps.md b/docs/zh/chat-apps.md index 2d6e55c3dd..026acf404e 100644 --- a/docs/zh/chat-apps.md +++ b/docs/zh/chat-apps.md @@ -15,7 +15,7 @@ PicoClaw 支持多种聊天平台,使您的 Agent 能够连接到任何地方 | **Telegram** | ⭐ 简单 | 推荐,支持语音转文字,长轮询无需公网 | [查看文档](../channels/telegram/README.zh.md) | | **Discord** | ⭐ 简单 | Socket Mode,支持群组/私信,Bot 生态成熟 | [查看文档](../channels/discord/README.zh.md) | | **WhatsApp** | ⭐ 简单 | 原生 (QR 扫码) 或 Bridge URL | [查看文档](#whatsapp) | -| **Weixin** | ⭐ 简单 | 原生扫码登录 (腾讯 iLink API) | [查看文档](../channels/weixin/README.zh.md) | +| **微信 (Weixin)** | ⭐ 简单 | 原生扫码(腾讯 iLink API) | [查看文档](#weixin) | | **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP),企业级支持 | [查看文档](../channels/slack/README.zh.md) | | **Matrix** | ⭐⭐ 中等 | 联邦协议,支持自建 homeserver 与公开服务器 | [查看文档](../channels/matrix/README.zh.md) | | **QQ** | ⭐⭐ 中等 | 官方机器人 API,适合国内社群 | [查看文档](../channels/qq/README.zh.md) | @@ -23,13 +23,14 @@ PicoClaw 支持多种聊天平台,使您的 Agent 能够连接到任何地方 | **LINE** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](../channels/line/README.zh.md) | | **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)、自建应用(API)和智能机器人(AI Bot) | [Bot 文档](../channels/wecom/wecom_bot/README.zh.md) / [App 文档](../channels/wecom/wecom_app/README.zh.md) / [AI Bot 文档](../channels/wecom/wecom_aibot/README.zh.md) | | **飞书 (Feishu)** | ⭐⭐⭐ 较难 | 企业级协作,功能丰富 | [查看文档](../channels/feishu/README.zh.md) | -| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | - | +| **IRC** | ⭐⭐ 中等 | 服务器 + TLS 配置 | [查看文档](#irc) | | **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP,社区生态丰富 | [查看文档](../channels/onebot/README.zh.md) | | **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](../channels/maixcam/README.zh.md) | | **Pico** | ⭐ 简单 | PicoClaw 原生协议通道 | | --- +
Telegram(推荐) @@ -70,6 +71,7 @@ Telegram 侧保留的是命令菜单注册能力;通用命令的实际执行
+
Discord @@ -144,6 +146,7 @@ picoclaw gateway
+
WhatsApp(原生 whatsmeow) @@ -171,27 +174,30 @@ PicoClaw 支持两种 WhatsApp 连接方式:
+
-Weixin (微信个人号) +微信 (Weixin) -PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。 +PicoClaw 通过腾讯 iLink 官方 API 支持连接微信个人号。 **1. 登录** + 运行交互式扫码登录流程: ```bash picoclaw onboard weixin ``` -在终端扫描打印出的二维码。登录成功后,Token 将自动保存到您的配置文件中。 +用微信手机端扫描打印出的二维码。登录成功后,token 会自动保存到配置文件。 **2. 配置** -(可选)更新 `allow_from` 填写微信 User ID,以限制哪些用户可以给机器人发消息: + +(可选)在 `allow_from` 中填入你的微信用户 ID,限制可以与机器人对话的用户: ```json { "channels": { "weixin": { "enabled": true, - "token": "你的_TOKEN", - "allow_from": ["你的_USER_ID"] + "token": "YOUR_TOKEN", + "allow_from": ["YOUR_USER_ID"] } } } @@ -204,6 +210,7 @@ picoclaw gateway
+
Matrix @@ -238,6 +245,7 @@ picoclaw gateway
+
QQ @@ -279,6 +287,7 @@ QQ 开放平台提供了一键创建 OpenClaw 兼容机器人的页面:
+
Slack @@ -312,6 +321,7 @@ picoclaw gateway
+
IRC @@ -345,6 +355,7 @@ Bot 将连接到 IRC 服务器并加入指定的频道。
+
钉钉 (DingTalk) @@ -379,6 +390,7 @@ picoclaw gateway
+
LINE @@ -427,6 +439,7 @@ picoclaw gateway
+
飞书 (Feishu) @@ -468,6 +481,7 @@ picoclaw gateway
+
企业微信 (WeCom) @@ -582,6 +596,7 @@ picoclaw gateway
+
OneBot(通过 OneBot 协议连接 QQ) @@ -620,6 +635,7 @@ picoclaw gateway
+
MaixCam diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md index 68fb1fd1ad..11aa4f1766 100644 --- a/docs/zh/configuration.md +++ b/docs/zh/configuration.md @@ -256,3 +256,356 @@ Agent 将每隔 30 分钟(可配置)读取此文件,并使用可用工具 - `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用 - `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔 + +#### 子 Agent 通信流程 + +``` +心跳触发 + ↓ +Agent 读取 HEARTBEAT.md + ↓ +遇到耗时任务:spawn 子 Agent + ↓ ↓ +继续处理下一个任务 子 Agent 独立运行 + ↓ ↓ +所有任务完成 子 Agent 使用 "message" 工具 + ↓ ↓ +回复 HEARTBEAT_OK 用户直接收到结果 +``` + +子 Agent 拥有工具访问权限(message、web_search 等),可以独立与用户通信,无需经过主 Agent。 + +### Providers(模型提供商) + +> [!NOTE] +> Groq 通过 Whisper 提供免费语音转录。配置后,任意渠道的语音消息都会在 Agent 层自动转录为文字。 + +| 提供商 | 用途 | 获取 API Key | +| ------------ | --------------------------------------- | ------------------------------------------------------------ | +| `gemini` | LLM(Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) | +| `zhipu` | LLM(智谱直连) | [bigmodel.cn](https://bigmodel.cn) | +| `volcengine` | LLM(火山引擎直连) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| `openrouter` | LLM(推荐,可访问所有模型) | [openrouter.ai](https://openrouter.ai) | +| `anthropic` | LLM(Claude 直连) | [console.anthropic.com](https://console.anthropic.com) | +| `openai` | LLM(GPT 直连) | [platform.openai.com](https://platform.openai.com) | +| `deepseek` | LLM(DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) | +| `qwen` | LLM(通义千问直连) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | +| `groq` | LLM + **语音转录**(Whisper) | [console.groq.com](https://console.groq.com) | +| `cerebras` | LLM(Cerebras 直连) | [cerebras.ai](https://cerebras.ai) | +| `vivgrid` | LLM(Vivgrid 直连) | [vivgrid.com](https://vivgrid.com) | + +### 模型配置 (model_list) + +> **新特性:** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式(例如 `zhipu/glm-4.7`)即可接入新提供商——**无需修改任何代码!** + +这一设计同时支持**多 Agent**场景,灵活选择提供商: + +- **不同 Agent 使用不同提供商**:每个 Agent 可以使用独立的 LLM 提供商 +- **模型降级**:配置主模型和备用模型,提升可用性 +- **负载均衡**:将请求分发到多个端点 +- **集中管理**:在一处管理所有提供商配置 + +#### 所有支持的厂商 + +| 厂商 | `model` 前缀 | 默认 API Base | 协议 | API Key | +| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- | +| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [获取](https://platform.openai.com) | +| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [获取](https://console.anthropic.com) | +| **智谱 AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | +| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [获取](https://platform.deepseek.com) | +| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [获取](https://aistudio.google.com/api-keys) | +| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [获取](https://console.groq.com) | +| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [获取](https://platform.moonshot.cn) | +| **通义千问 (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [获取](https://dashscope.console.aliyun.com) | +| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [获取](https://build.nvidia.com) | +| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | 本地(无需 Key) | +| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [获取](https://openrouter.ai/keys) | +| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | 你的 LiteLLM 代理 Key | +| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | 本地 | +| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [获取](https://cerebras.ai) | +| **火山引擎 (豆包)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | +| **神算云** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | — | +| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [获取](https://www.byteplus.com) | +| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [获取](https://vivgrid.com) | +| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [获取](https://longcat.chat/platform) | +| **ModelScope (魔搭)** | `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [获取](https://modelscope.cn/my/tokens) | +| **Antigravity** | `antigravity/` | Google Cloud | Custom | 仅 OAuth | +| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | — | + +#### 基础配置 + +```json +{ + "model_list": [ + { + "model_name": "ark-code-latest", + "model": "volcengine/ark-code-latest", + "api_key": "sk-your-api-key" + }, + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-your-openai-key" + }, + { + "model_name": "claude-sonnet-4.6", + "model": "anthropic/claude-sonnet-4.6", + "api_key": "sk-ant-your-key" + }, + { + "model_name": "glm-4.7", + "model": "zhipu/glm-4.7", + "api_key": "your-zhipu-key" + } + ], + "agents": { + "defaults": { + "model": "gpt-5.4" + } + } +} +``` + +#### 各厂商配置示例 + +
+OpenAI + +```json +{ + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_key": "sk-..." +} +``` + +
+ +
+火山引擎(豆包) + +```json +{ + "model_name": "ark-code-latest", + "model": "volcengine/ark-code-latest", + "api_key": "sk-..." +} +``` + +
+ +
+智谱 AI (GLM) + +```json +{ + "model_name": "glm-4.7", + "model": "zhipu/glm-4.7", + "api_key": "your-key" +} +``` + +
+ +
+DeepSeek + +```json +{ + "model_name": "deepseek-chat", + "model": "deepseek/deepseek-chat", + "api_key": "sk-..." +} +``` + +
+ +
+Anthropic + +```json +{ + "model_name": "claude-sonnet-4.6", + "model": "anthropic/claude-sonnet-4.6", + "api_key": "sk-ant-your-key" +} +``` + +> 运行 `picoclaw auth login --provider anthropic` 粘贴 API Token。 + +如需直连 Anthropic 原生接口(不兼容 OpenAI 格式的端点): + +```json +{ + "model_name": "claude-opus-4-6", + "model": "anthropic-messages/claude-opus-4-6", + "api_key": "sk-ant-your-key", + "api_base": "https://api.anthropic.com" +} +``` + +> 当端点不支持 OpenAI 兼容格式(`/v1/chat/completions`),需要 Anthropic 原生 `/v1/messages` 时使用 `anthropic-messages`。 + +
+ +
+Ollama(本地) + +```json +{ + "model_name": "llama3", + "model": "ollama/llama3" +} +``` + +
+ +
+自定义代理 / LiteLLM + +```json +{ + "model_name": "my-custom-model", + "model": "openai/custom-model", + "api_base": "https://my-proxy.com/v1", + "api_key": "sk-..." +} +``` + +PicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求,因此 `litellm/lite-gpt4` 发送 `lite-gpt4`,而 `litellm/openai/gpt-4o` 发送 `openai/gpt-4o`。 + +
+ +#### 负载均衡 + +为同一模型名称配置多个端点,PicoClaw 会自动轮询: + +```json +{ + "model_list": [ + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_base": "https://api1.example.com/v1", + "api_key": "sk-key1" + }, + { + "model_name": "gpt-5.4", + "model": "openai/gpt-5.4", + "api_base": "https://api2.example.com/v1", + "api_key": "sk-key2" + } + ] +} +``` + +#### 从旧版 `providers` 配置迁移 + +旧版 `providers` 配置**已废弃**,但仍向后兼容。完整迁移指南见 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。 + +### Provider 架构 + +PicoClaw 按协议族路由提供商: + +- **OpenAI 兼容**:OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。 +- **Anthropic**:Claude 原生 API 行为。 +- **Codex/OAuth**:OpenAI OAuth/Token 认证路由。 + +这使运行时保持轻量,同时让接入新的 OpenAI 兼容后端基本只需配置 `api_base` + `api_key`。 + +
+智谱(旧版 providers 格式) + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model": "glm-4.7", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "providers": { + "zhipu": { + "api_key": "Your API Key", + "api_base": "https://open.bigmodel.cn/api/paas/v4" + } + } +} +``` + +
+ +
+完整配置示例 + +```json +{ + "agents": { + "defaults": { + "model": "anthropic/claude-opus-4-5" + } + }, + "session": { + "dm_scope": "per-channel-peer", + "backlog_limit": 20 + }, + "providers": { + "openrouter": { + "api_key": "sk-or-v1-xxx" + }, + "groq": { + "api_key": "gsk_xxx" + } + }, + "channels": { + "telegram": { + "enabled": true, + "token": "123456:ABC...", + "allow_from": ["123456789"] + } + }, + "tools": { + "web": { + "duckduckgo": { + "enabled": true, + "max_results": 5 + } + } + }, + "heartbeat": { + "enabled": true, + "interval": 30 + } +} +``` + +
+ +### 定时任务 / 提醒 + +PicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。 + +```json +{ + "tools": { + "cron": { + "enabled": true, + "exec_timeout_minutes": 5 + } + } +} +``` + +定时任务在重启后持久保存,存储于 `~/.picoclaw/workspace/cron/`。 + +### 进阶主题 + +| 主题 | 说明 | +| ---- | ---- | +| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook:观察者、拦截器、审批 Hook | +| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 | +| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 | +| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 | diff --git a/docs/zh/tools_configuration.md b/docs/zh/tools_configuration.md index f134489523..a3816a35a7 100644 --- a/docs/zh/tools_configuration.md +++ b/docs/zh/tools_configuration.md @@ -41,17 +41,54 @@ Web 工具用于网页搜索和抓取。 | `fetch_limit_bytes` | int | 10485760 | 抓取网页负载的最大大小,单位为字节(默认 10MB)。 | | `format` | string | "plaintext" | 抓取内容的输出格式。选项:`plaintext` 或 `markdown`(推荐)。 | -### Brave +### 百度搜索 -| 配置项 | 类型 | 默认值 | 描述 | -|---------------|----------|--------|------------------------------------------------| -| `enabled` | bool | false | 启用 Brave 搜索 | -| `api_key` | string | - | Brave Search API 密钥 | -| `api_keys` | string[] | - | 多个 API 密钥轮换(优先于 `api_key`) | -| `max_results` | int | 5 | 最大结果数 | +使用[千帆 AI 搜索 API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5),国内访问稳定,中文搜索效果好。 + +| 配置项 | 类型 | 默认值 | 描述 | +|---------------|--------|----------------------------------------------------------------|-----------------------| +| `enabled` | bool | false | 启用百度搜索 | +| `api_key` | string | - | 千帆 API 密钥 | +| `base_url` | string | `https://qianfan.baidubce.com/v2/ai_search/web_search` | 百度搜索 API URL | +| `max_results` | int | 10 | 最大结果数 | + +```json +{ + "tools": { + "web": { + "baidu_search": { + "enabled": true, + "api_key": "YOUR_BAIDU_QIANFAN_API_KEY", + "max_results": 10 + } + } + } +} +``` + +### Tavily + +| 配置项 | 类型 | 默认值 | 描述 | +|---------------|--------|--------|-----------------------------------| +| `enabled` | bool | false | 启用 Tavily 搜索 | +| `api_key` | string | - | Tavily API 密钥 | +| `base_url` | string | - | 自定义 Tavily API 基础 URL | +| `max_results` | int | 0 | 最大结果数(0 = 默认) | + +### GLM Search + +| 配置项 | 类型 | 默认值 | 描述 | +|-----------------|--------|------------------------------------------------------|-----------------------| +| `enabled` | bool | false | 启用 GLM 搜索 | +| `api_key` | string | - | GLM API 密钥 | +| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL | +| `search_engine` | string | `search_std` | 搜索引擎类型 | +| `max_results` | int | 5 | 最大结果数 | ### DuckDuckGo +> ⚠️ 国内访问困难,建议搭配代理使用。 + | 配置项 | 类型 | 默认值 | 描述 | |---------------|------|--------|-----------------------| | `enabled` | bool | true | 启用 DuckDuckGo 搜索 | @@ -59,6 +96,8 @@ Web 工具用于网页搜索和抓取。 ### Perplexity +> ⚠️ 国内访问困难,建议搭配代理使用。 + | 配置项 | 类型 | 默认值 | 描述 | |---------------|----------|--------|------------------------------------------------| | `enabled` | bool | false | 启用 Perplexity 搜索 | @@ -66,14 +105,16 @@ Web 工具用于网页搜索和抓取。 | `api_keys` | string[] | - | 多个 API 密钥轮换(优先于 `api_key`) | | `max_results` | int | 5 | 最大结果数 | -### Tavily +### Brave -| 配置项 | 类型 | 默认值 | 描述 | -|---------------|--------|--------|-----------------------------------| -| `enabled` | bool | false | 启用 Tavily 搜索 | -| `api_key` | string | - | Tavily API 密钥 | -| `base_url` | string | - | 自定义 Tavily API 基础 URL | -| `max_results` | int | 0 | 最大结果数(0 = 默认) | +> ⚠️ 国内访问困难,建议搭配代理使用。 + +| 配置项 | 类型 | 默认值 | 描述 | +|---------------|----------|--------|------------------------------------------------| +| `enabled` | bool | false | 启用 Brave 搜索 | +| `api_key` | string | - | Brave Search API 密钥 | +| `api_keys` | string[] | - | 多个 API 密钥轮换(优先于 `api_key`) | +| `max_results` | int | 5 | 最大结果数 | ### SearXNG @@ -83,16 +124,6 @@ Web 工具用于网页搜索和抓取。 | `base_url` | string | `http://localhost:8888` | SearXNG 实例 URL | | `max_results` | int | 5 | 最大结果数 | -### GLM Search - -| 配置项 | 类型 | 默认值 | 描述 | -|-----------------|--------|------------------------------------------------------|-----------------------| -| `enabled` | bool | false | 启用 GLM 搜索 | -| `api_key` | string | - | GLM API 密钥 | -| `base_url` | string | `https://open.bigmodel.cn/api/paas/v4/web_search` | GLM Search API URL | -| `search_engine` | string | `search_std` | 搜索引擎类型 | -| `max_results` | int | 5 | 最大结果数 | - ### 其他 Web 设置 | 配置项 | 类型 | 默认值 | 描述 | diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go index 840aa8fa1a..354b8865ec 100644 --- a/pkg/agent/loop.go +++ b/pkg/agent/loop.go @@ -174,17 +174,21 @@ func registerSharedTools( cfg.Tools.Web.Perplexity.APIKey, cfg.Tools.Web.Perplexity.APIKeys, ), - PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults, - PerplexityEnabled: cfg.Tools.Web.Perplexity.Enabled, - SearXNGBaseURL: cfg.Tools.Web.SearXNG.BaseURL, - SearXNGMaxResults: cfg.Tools.Web.SearXNG.MaxResults, - SearXNGEnabled: cfg.Tools.Web.SearXNG.Enabled, - GLMSearchAPIKey: cfg.Tools.Web.GLMSearch.APIKey, - GLMSearchBaseURL: cfg.Tools.Web.GLMSearch.BaseURL, - GLMSearchEngine: cfg.Tools.Web.GLMSearch.SearchEngine, - GLMSearchMaxResults: cfg.Tools.Web.GLMSearch.MaxResults, - GLMSearchEnabled: cfg.Tools.Web.GLMSearch.Enabled, - Proxy: cfg.Tools.Web.Proxy, + PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults, + PerplexityEnabled: cfg.Tools.Web.Perplexity.Enabled, + SearXNGBaseURL: cfg.Tools.Web.SearXNG.BaseURL, + SearXNGMaxResults: cfg.Tools.Web.SearXNG.MaxResults, + SearXNGEnabled: cfg.Tools.Web.SearXNG.Enabled, + GLMSearchAPIKey: cfg.Tools.Web.GLMSearch.APIKey, + GLMSearchBaseURL: cfg.Tools.Web.GLMSearch.BaseURL, + GLMSearchEngine: cfg.Tools.Web.GLMSearch.SearchEngine, + GLMSearchMaxResults: cfg.Tools.Web.GLMSearch.MaxResults, + GLMSearchEnabled: cfg.Tools.Web.GLMSearch.Enabled, + BaiduSearchAPIKey: cfg.Tools.Web.BaiduSearch.APIKey, + BaiduSearchBaseURL: cfg.Tools.Web.BaiduSearch.BaseURL, + BaiduSearchMaxResults: cfg.Tools.Web.BaiduSearch.MaxResults, + BaiduSearchEnabled: cfg.Tools.Web.BaiduSearch.Enabled, + Proxy: cfg.Tools.Web.Proxy, }) if err != nil { logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()}) diff --git a/pkg/config/config.go b/pkg/config/config.go index 7c7b79959a..8dd86bd520 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -792,14 +792,22 @@ type GLMSearchConfig struct { MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_GLM_MAX_RESULTS"` } +type BaiduSearchConfig struct { + Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_BAIDU_ENABLED"` + APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_BAIDU_API_KEY"` + BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_BAIDU_BASE_URL"` + MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BAIDU_MAX_RESULTS"` +} + type WebToolsConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` - Brave BraveConfig ` json:"brave"` - Tavily TavilyConfig ` json:"tavily"` - DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` - Perplexity PerplexityConfig ` json:"perplexity"` - SearXNG SearXNGConfig ` json:"searxng"` - GLMSearch GLMSearchConfig ` json:"glm_search"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` + Brave BraveConfig ` json:"brave"` + Tavily TavilyConfig ` json:"tavily"` + DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` + Perplexity PerplexityConfig ` json:"perplexity"` + SearXNG SearXNGConfig ` json:"searxng"` + GLMSearch GLMSearchConfig ` json:"glm_search"` + BaiduSearch BaiduSearchConfig ` json:"baidu_search"` // PreferNative controls whether to use provider-native web search when // the active LLM supports it (e.g. OpenAI web_search_preview). When true, // the client-side web_search tool is hidden to avoid duplicate search surfaces, diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go index 3397eb91cd..b04a42a5f7 100644 --- a/pkg/config/defaults.go +++ b/pkg/config/defaults.go @@ -475,6 +475,12 @@ func DefaultConfig() *Config { SearchEngine: "search_std", MaxResults: 5, }, + BaiduSearch: BaiduSearchConfig{ + Enabled: false, + APIKey: "", + BaseURL: "https://qianfan.baidubce.com/v2/ai_search/web_search", + MaxResults: 10, + }, }, Cron: CronToolsConfig{ ToolConfig: ToolConfig{ diff --git a/pkg/tools/web.go b/pkg/tools/web.go index 42cf795787..41e91f0848 100644 --- a/pkg/tools/web.go +++ b/pkg/tools/web.go @@ -613,39 +613,120 @@ func (p *GLMSearchProvider) Search(ctx context.Context, query string, count int) return strings.Join(lines, "\n"), nil } +type BaiduSearchProvider struct { + apiKey string + baseURL string + proxy string + client *http.Client +} + +func (p *BaiduSearchProvider) Search(ctx context.Context, query string, count int) (string, error) { + searchURL := p.baseURL + if searchURL == "" { + searchURL = "https://qianfan.baidubce.com/v2/ai_search/web_search" + } + + payload := map[string]any{ + "messages": []map[string]string{ + { + "role": "user", + "content": query, + }, + }, + "search_source": "baidu_search_v2", + "resource_type_filter": []map[string]any{{"type": "web", "top_k": count}}, + } + + bodyBytes, err := json.Marshal(payload) + if err != nil { + return "", fmt.Errorf("failed to marshal payload: %w", err) + } + + req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewReader(bodyBytes)) + if err != nil { + return "", fmt.Errorf("failed to create request: %w", err) + } + + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Authorization", "Bearer "+p.apiKey) + + resp, err := p.client.Do(req) + if err != nil { + return "", fmt.Errorf("baidu search request failed: %w", err) + } + defer resp.Body.Close() + + body, err := io.ReadAll(resp.Body) + if err != nil { + return "", fmt.Errorf("failed to read response: %w", err) + } + + if resp.StatusCode != http.StatusOK { + return "", fmt.Errorf("baidu search API error %d: %s", resp.StatusCode, string(body)) + } + + var result struct { + References []struct { + Title string `json:"title"` + URL string `json:"url"` + Content string `json:"content"` + } `json:"references"` + } + if err := json.Unmarshal(body, &result); err != nil { + return "", fmt.Errorf("failed to parse response: %w", err) + } + + var lines []string + for i, item := range result.References { + if i >= count { + break + } + lines = append(lines, fmt.Sprintf("%d. %s\n %s", i+1, item.Title, item.URL)) + if item.Content != "" { + lines = append(lines, fmt.Sprintf(" %s", item.Content)) + } + } + + return strings.Join(lines, "\n"), nil +} + type WebSearchTool struct { provider SearchProvider maxResults int } type WebSearchToolOptions struct { - BraveAPIKeys []string - BraveMaxResults int - BraveEnabled bool - TavilyAPIKeys []string - TavilyBaseURL string - TavilyMaxResults int - TavilyEnabled bool - DuckDuckGoMaxResults int - DuckDuckGoEnabled bool - PerplexityAPIKeys []string - PerplexityMaxResults int - PerplexityEnabled bool - SearXNGBaseURL string - SearXNGMaxResults int - SearXNGEnabled bool - GLMSearchAPIKey string - GLMSearchBaseURL string - GLMSearchEngine string - GLMSearchMaxResults int - GLMSearchEnabled bool - Proxy string + BraveAPIKeys []string + BraveMaxResults int + BraveEnabled bool + TavilyAPIKeys []string + TavilyBaseURL string + TavilyMaxResults int + TavilyEnabled bool + DuckDuckGoMaxResults int + DuckDuckGoEnabled bool + PerplexityAPIKeys []string + PerplexityMaxResults int + PerplexityEnabled bool + SearXNGBaseURL string + SearXNGMaxResults int + SearXNGEnabled bool + GLMSearchAPIKey string + GLMSearchBaseURL string + GLMSearchEngine string + GLMSearchMaxResults int + GLMSearchEnabled bool + BaiduSearchAPIKey string + BaiduSearchBaseURL string + BaiduSearchMaxResults int + BaiduSearchEnabled bool + Proxy string } func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) { var provider SearchProvider maxResults := 5 - // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > GLM Search + // Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > Baidu Search > GLM Search if opts.PerplexityEnabled && len(opts.PerplexityAPIKeys) > 0 { client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout) if err != nil { @@ -696,6 +777,20 @@ func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) { if opts.DuckDuckGoMaxResults > 0 { maxResults = opts.DuckDuckGoMaxResults } + } else if opts.BaiduSearchEnabled && opts.BaiduSearchAPIKey != "" { + client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout) + if err != nil { + return nil, fmt.Errorf("failed to create HTTP client for Baidu Search: %w", err) + } + provider = &BaiduSearchProvider{ + apiKey: opts.BaiduSearchAPIKey, + baseURL: opts.BaiduSearchBaseURL, + proxy: opts.Proxy, + client: client, + } + if opts.BaiduSearchMaxResults > 0 { + maxResults = opts.BaiduSearchMaxResults + } } else if opts.GLMSearchEnabled && opts.GLMSearchAPIKey != "" { client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout) if err != nil { From 30db9939938b23e0d84231dfddfe9a41eb9432b1 Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 00:54:50 +0800 Subject: [PATCH 2/6] fix(lint): fix golines line length in WebToolsConfig struct Remove extra alignment space on ToolConfig field introduced by gofumpt when BaiduSearchConfig was added, keeping all lines under 120 chars. Co-Authored-By: Claude Opus 4.6 --- pkg/config/config.go | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pkg/config/config.go b/pkg/config/config.go index 8dd86bd520..334f75a632 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -800,14 +800,14 @@ type BaiduSearchConfig struct { } type WebToolsConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` - Brave BraveConfig ` json:"brave"` - Tavily TavilyConfig ` json:"tavily"` - DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` - Perplexity PerplexityConfig ` json:"perplexity"` - SearXNG SearXNGConfig ` json:"searxng"` - GLMSearch GLMSearchConfig ` json:"glm_search"` - BaiduSearch BaiduSearchConfig ` json:"baidu_search"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` + Brave BraveConfig ` json:"brave"` + Tavily TavilyConfig ` json:"tavily"` + DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` + Perplexity PerplexityConfig ` json:"perplexity"` + SearXNG SearXNGConfig ` json:"searxng"` + GLMSearch GLMSearchConfig ` json:"glm_search"` + BaiduSearch BaiduSearchConfig ` json:"baidu_search"` // PreferNative controls whether to use provider-native web search when // the active LLM supports it (e.g. OpenAI web_search_preview). When true, // the client-side web_search tool is hidden to avoid duplicate search surfaces, From b150d7d52329e14a7242e66d1481bea7a3717a0b Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 00:57:14 +0800 Subject: [PATCH 3/6] fix(lint): fix gci import formatting in config.go Co-Authored-By: Claude Opus 4.6 --- pkg/config/config.go | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pkg/config/config.go b/pkg/config/config.go index 334f75a632..c212998745 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -800,13 +800,13 @@ type BaiduSearchConfig struct { } type WebToolsConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` - Brave BraveConfig ` json:"brave"` - Tavily TavilyConfig ` json:"tavily"` - DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` - Perplexity PerplexityConfig ` json:"perplexity"` - SearXNG SearXNGConfig ` json:"searxng"` - GLMSearch GLMSearchConfig ` json:"glm_search"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` + Brave BraveConfig ` json:"brave"` + Tavily TavilyConfig ` json:"tavily"` + DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` + Perplexity PerplexityConfig ` json:"perplexity"` + SearXNG SearXNGConfig ` json:"searxng"` + GLMSearch GLMSearchConfig ` json:"glm_search"` BaiduSearch BaiduSearchConfig ` json:"baidu_search"` // PreferNative controls whether to use provider-native web search when // the active LLM supports it (e.g. OpenAI web_search_preview). When true, From c786f35b3274d3af0de44479aac8593a2407549f Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 01:03:49 +0800 Subject: [PATCH 4/6] fix(lint): fix golines/gci formatting in WebToolsConfig Run golines then gci to reach a stable state that satisfies both linters. BaiduSearchConfig field caused gofumpt to re-align the struct, shifting ToolConfig tag spacing and triggering golines on each subsequent fix. Co-Authored-By: Claude Opus 4.6 --- pkg/config/config.go | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/pkg/config/config.go b/pkg/config/config.go index c212998745..fef256d136 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -783,9 +783,9 @@ type SearXNGConfig struct { } type GLMSearchConfig struct { - Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"` - APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"` - BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"` + Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"` + APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"` + BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"` // SearchEngine specifies the search backend: "search_std" (default), // "search_pro", "search_pro_sogou", or "search_pro_quark". SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"` @@ -800,26 +800,26 @@ type BaiduSearchConfig struct { } type WebToolsConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` Brave BraveConfig ` json:"brave"` Tavily TavilyConfig ` json:"tavily"` DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` Perplexity PerplexityConfig ` json:"perplexity"` SearXNG SearXNGConfig ` json:"searxng"` GLMSearch GLMSearchConfig ` json:"glm_search"` - BaiduSearch BaiduSearchConfig ` json:"baidu_search"` + BaiduSearch BaiduSearchConfig ` json:"baidu_search"` // PreferNative controls whether to use provider-native web search when // the active LLM supports it (e.g. OpenAI web_search_preview). When true, // the client-side web_search tool is hidden to avoid duplicate search surfaces, // and the provider's built-in search is used instead. Falls back to client-side // search when the provider does not support native search. - PreferNative bool `json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"` + PreferNative bool ` json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"` // Proxy is an optional proxy URL for web tools (http/https/socks5/socks5h). // For authenticated proxies, prefer HTTP_PROXY/HTTPS_PROXY env vars instead of embedding credentials in config. - Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"` - FetchLimitBytes int64 `json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"` - Format string `json:"format,omitempty" env:"PICOCLAW_TOOLS_WEB_FORMAT"` - PrivateHostWhitelist FlexibleStringSlice `json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"` + Proxy string ` json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"` + FetchLimitBytes int64 ` json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"` + Format string ` json:"format,omitempty" env:"PICOCLAW_TOOLS_WEB_FORMAT"` + PrivateHostWhitelist FlexibleStringSlice ` json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"` } type CronToolsConfig struct { @@ -934,10 +934,10 @@ type MCPServerConfig struct { // MCPConfig defines configuration for all MCP servers type MCPConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_MCP_"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_MCP_"` Discovery ToolDiscoveryConfig ` json:"discovery"` // Servers is a map of server name to server configuration - Servers map[string]MCPServerConfig `json:"servers,omitempty"` + Servers map[string]MCPServerConfig ` json:"servers,omitempty"` } func LoadConfig(path string) (*Config, error) { From 4bc64497e30939d77da0f77750c8dd9de7d08635 Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 01:10:09 +0800 Subject: [PATCH 5/6] fix(lint): run golangci-lint fmt to fix golines/gci struct tag formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit golangci-lint v2.10.1 treats golines as a formatter. Running `golangci-lint fmt` normalizes struct tag alignment in GLMSearchConfig, WebToolsConfig, and MCPConfig — removing manual padding that golines flagged as improperly formatted. Co-Authored-By: Claude Opus 4.6 --- pkg/config/config.go | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/pkg/config/config.go b/pkg/config/config.go index fef256d136..edd22d180b 100644 --- a/pkg/config/config.go +++ b/pkg/config/config.go @@ -783,9 +783,9 @@ type SearXNGConfig struct { } type GLMSearchConfig struct { - Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"` - APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"` - BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"` + Enabled bool `json:"enabled" env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"` + APIKey string `json:"api_key" env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"` + BaseURL string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"` // SearchEngine specifies the search backend: "search_std" (default), // "search_pro", "search_pro_sogou", or "search_pro_quark". SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"` @@ -800,7 +800,7 @@ type BaiduSearchConfig struct { } type WebToolsConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_WEB_"` Brave BraveConfig ` json:"brave"` Tavily TavilyConfig ` json:"tavily"` DuckDuckGo DuckDuckGoConfig ` json:"duckduckgo"` @@ -813,13 +813,13 @@ type WebToolsConfig struct { // the client-side web_search tool is hidden to avoid duplicate search surfaces, // and the provider's built-in search is used instead. Falls back to client-side // search when the provider does not support native search. - PreferNative bool ` json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"` + PreferNative bool `json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"` // Proxy is an optional proxy URL for web tools (http/https/socks5/socks5h). // For authenticated proxies, prefer HTTP_PROXY/HTTPS_PROXY env vars instead of embedding credentials in config. - Proxy string ` json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"` - FetchLimitBytes int64 ` json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"` - Format string ` json:"format,omitempty" env:"PICOCLAW_TOOLS_WEB_FORMAT"` - PrivateHostWhitelist FlexibleStringSlice ` json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"` + Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_WEB_PROXY"` + FetchLimitBytes int64 `json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"` + Format string `json:"format,omitempty" env:"PICOCLAW_TOOLS_WEB_FORMAT"` + PrivateHostWhitelist FlexibleStringSlice `json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"` } type CronToolsConfig struct { @@ -934,10 +934,10 @@ type MCPServerConfig struct { // MCPConfig defines configuration for all MCP servers type MCPConfig struct { - ToolConfig ` envPrefix:"PICOCLAW_TOOLS_MCP_"` + ToolConfig ` envPrefix:"PICOCLAW_TOOLS_MCP_"` Discovery ToolDiscoveryConfig ` json:"discovery"` // Servers is a map of server name to server configuration - Servers map[string]MCPServerConfig ` json:"servers,omitempty"` + Servers map[string]MCPServerConfig `json:"servers,omitempty"` } func LoadConfig(path string) (*Config, error) { From 48cba906cd46da1c118270d16abad23959c9c451 Mon Sep 17 00:00:00 2001 From: BeaconCat Date: Mon, 23 Mar 2026 10:21:06 +0800 Subject: [PATCH 6/6] fix: restore missing assets and address Copilot review comments - Add hardware-banner.jpg, launcher-webui.jpg, launcher-tui.jpg (lost in previous force push) - Add io.LimitReader (1MB) to BaiduSearchProvider response body read - Add no-results fallback and "Results for: ... (via Baidu Search)" header - Add api_keys field to Brave and Perplexity tables in fr/ja/pt-br/vi tools_configuration.md Co-Authored-By: Claude Opus 4.6 --- assets/hardware-banner.jpg | Bin 0 -> 233742 bytes assets/launcher-tui.jpg | Bin 0 -> 104417 bytes assets/launcher-webui.jpg | Bin 0 -> 212810 bytes docs/fr/tools_configuration.md | 14 ++++++++------ docs/ja/tools_configuration.md | 14 ++++++++------ docs/pt-br/tools_configuration.md | 14 ++++++++------ docs/vi/tools_configuration.md | 14 ++++++++------ pkg/tools/web.go | 8 ++++++-- 8 files changed, 38 insertions(+), 26 deletions(-) create mode 100644 assets/hardware-banner.jpg create mode 100644 assets/launcher-tui.jpg create mode 100644 assets/launcher-webui.jpg diff --git a/assets/hardware-banner.jpg b/assets/hardware-banner.jpg new file mode 100644 index 0000000000000000000000000000000000000000..f9a1190b1eddbe7ff7897ddac422bca88c0f4b89 GIT binary patch literal 233742 zcmbT71yogC`{2(F8l<~Bq`SKtq`SKtBn3f08j%jAyGtn%=`IQBE`du(55C{b_y1E> z{n?Vs%G%TNnIoRr$=A#6um1FzaV#AFG8p=oJ)Sf8%mjbg_Fv5WkIlbW{4ZNMyI4Kj z{LQnQm9y1f{{GDGe7von8KV5mkv{g;zRx`K%rs8k&i2pz=b3Swt<60F0E+ro?`3Ui z_ss0ijOwAKDfP_4&kc!c`yXuaAM9oA_nc1vkaBhN_prCM^P*s|WTfB_5a6efxAt|i z_VQv;H@9>&_pqXna&>kycku^+f0g-fC;;nk-BLVPGB1Y!FE0xx>vQ%0TmG+}|F-(S z!{4_3mjz7YpEd*Gjr^DHzry~P&h--j@LxXHP2zv)EHVI~Dr9u%H#=9bnJEdOgK{{Ig6AKChkd@yTT+gN*8yF4eQ^W4kqU2LD5+r`S> z%ih(6!rtZo)WZLt!Tuu;fAL@a`Wdhb9|0UwRsdrh2Y?)p08nfc0AiH;>;w9DyD1~- z0DniGF8S`i`u#IM`~TzqPYyWY`4a4DZ%gr4Ev2bNVd?GR^Ov8;#9s#vKnBnO9DooY z1E>K8fCb?AP@)xB7s;S5%>UP0(n3oPzF>3 z^*{^o73cwe0K>opFbgaJYrr;e2%G{}z#Rw#LI9zGut9_%au6-(C5RKm4-y5*fRsU+ zAbpS-$QI-R@&*Nh!a=d1WKbrk08|F51GRyAK!c!3&;n>3v=2H5-GU)tR4@*h6if$Z z1M`C=z)D~(urb&c><$h9M}XtO>EKV`N^mo{2Rsa(1+Re*!IuyKf&#&VP(oNB{17RK z8pHr%1Mz?aLt-FlkWY|mNIRq-G7VXS96@fN@K9_h1(XFU1eJ$sLoK21&|v6$XeP82 z+6?^;orbPMPoa-+XmBKOFX05?6yWsWY~g(2BH_~Dis72z`ru~aw&AYe;oEZd{ z<>B?=9pGQXzlYC(uYvD|pM>9pzeGSlAVheHAcCNVV2IlmFom#<@COkE zksOf|Q5Mkv(FO4hVj5yOVkhDh;x6JH5(W}2k|2^Ak`rbpaKIhK5FmCXQx+=7koIR)*G#wu1KO1@;Tp7YZ+|UWB~JdeQu1>ct5<5;`rq z1iA@&0D2mF1Nu1n5e57DgM!JjNv^HYNwA8m2Smd(3joLCifY1S~o% z87wQT2&~Uoy;z&r5Nv8}DQrvZaO^_tKJ0BAcpQ2h1sn&QSez=HF`QFeEL?6}9b7-$ zEZh#DGNEj}r}1im$XG=4Sy6#g{n*4mL@ z3xzjDs6@;~3PjdKDMZag^F`OhD8epftB=Q`>3(k;?$&0Wy_gZrt6l1H&8 z$kW)f)eGl&Gd1GP;QiKn-AB|X%jb`;j&Fk>rk{)7h(D8mwEu2^Y(UX#=xfW@-vTKE z!vfcXB!UWpLBSTm-$JNEB0{!9Q@P@~)p?|Ov3a-o_W3^xSQCTrj zacuEJiA%{^sb=Z-GQP61a+30d3UGyY#eStx8Yt>s@ecI=`L6MOtWT+L;D_vw-hPSxt^tvOuY-bvZA1J+ zEyKLS%_BS`O`|-cO=G-c&EtIItrG$h?UTZjol{~{J=41e$E@s zul=<8xwqi7aJJ~Pc()X~47VKf3*%SX3dzc+RmRntHQu$3b?NnyjaM5>o0gl0Tb^6@ z+YvixJ88S*yJdTvdtdiu_a_bv54I284)2a4k1>z4PZ&-be~bSfIn_JeKJz$xI)4u% zgq2)yUwpe%zg)R;zPh`P`9t`p^oIYY|5o>Q_s;ho;XeI=@uB@u>2dkV`RVED1fZ0# za<#Aqti+%90w4&00Rcn)bu{_AIe3<*B_IL-gP+%42owy4!a*TWIC!{cfk%8^%McI{ zQIP(T=SAlqLH*we2m*m1KoQUo5YW({*Bo^87tex@{*UQ@|3UrN)&DN^v+n5|fQbl7 zM3{hpFaaubgwF{-2Li!^ zpI3M|M0havb9?|MloAV$Lqfxx3LD-%3?r$4Qxd1HXHt_I*TN&2iw1#W{Y|~p>8Dqg zo(8fwgjqMVj(qLsbX zl{uzMG#DO-Y$~5!Uul4nol~S!J$}Vb&h{nzpJ5DKF32MaARE`o?)KjR^A|lj8oEU~?r1IrgoJi=hfqj!I78M=jE?&c(R-JMSPuwUY>=6gukpw?S8jeg}9d`fr&!<>`bjLWi%TT<-ixVu~$+8yW=H*5+LJC{9 z#$Cs!Y zaf)Zv6A6DV6gDJJY+$l-^*c}Tm8wQeOT~iD*uaD|@A#>UDCfa}#&_E-qe1$7Qw$GyA6A>j?hm+)|N^lMI0v zVD$~>O(I8nQbRU%K8(z|Ol^@&0de}J7InJn*CM(k>M(WyY$uLEh{}Ys@PZnSi~n=n1Mn)^HF%ptvj*8~fvzD&^^YTsOCCTHR;4M4!$s06)?h!Adk zj^nfNtMeYAHZ#(%lPm8vH5mzPFn6ptA>zH1YuL~Pb~}D}kQ$3MfwJ=l7DP@Z7j4^9 z@8i|5BSqTVKCmj)9!W+))2ry0NH7Q;OBt<{9tNmHM$v9RH@h4);PdkBh=3pqt20Yr z|MB_f4plU{%lq<%&ooBHW6MFhyXdlmXFhsW(m}3#CL(#PsTce&2Qz*cT2?SG^Yca{ zYtUiG$qxciaXu?X({vYj&LjCS2PjVDU>N|ISB%JL#Z z?j)s_7!jE^bqW!vqhFfWJ=F2J6H&lD^>!CwN=S3BwdJZhjlMl(SG;&r74YM7FMdVF z)~|4JyNKI9Kiy)pc}xXkSX?d9z`9(Ch9nI%C_9VWuKXaCfK4*v>5Qj5H6;d4=xQ z7a(yd_PRFM|G6++_qop6>ev;ooH^arDS%iGOLo`sR^_8N^%^BOA`S~D+QgE0I=#$& z41l%7!~GiS?X=Hi&g12_f{r7EBf>cILRAojA*lJv82<2pegt1QEiWEtL8mm%G^n(l zUnqd~d}VVkv7pB?UMFs5LS0=*fhJny+c!5dXHF|LQl=+Bqa-U}Gof4~E305vS!*BI z`_Xzd*tvoJq4CTcLR$IW+xEhrp~i9OlZYB8>Ff~Q@~eQz<;gj`=|xTGoQgH4?=a&n z1Ciu?w6OJ}DgKO$CZqj+KWG3=vm3M^mb1K>`_AK2ZT;zNSMs73Biw}fp8T{7Wu_~V56Kgt_~^?_-hCmB z1auP+fFVh!hg+LZz@DiH#>q}4PwGvwpZiIgLUgEGo!yH#V`)L=WMEoMg)K2Q_4@`F zcY|yyK!^?x84>M6HR{(9ws;}qk6cOY0O?sfHN)oM$6rm+ZxNS&6VvdGQ=rALoJ79q*X`CUzzo4kaZK)9qc8dbUc z_bKf3-0$yL&;{nzIt^Fb*%xr>hFX6$sW7D$m3&~`pyW(ZW~bw>S|SDnrF+fVpvRA~91oERnZffw)icss~N> zGb1OG1$?0#W&g%D+Ca6z8gC-NxGk&D&?~*sfp4Nyw;qMEXL{$Zg3=`-ln>IoY13tJO*-$11fztTpnD6ena2Jp zDU3P9b`~QUlW=b&QJo3PNrvnwwCXbZ6m^!2OTglkHfPS>f!9SpO_Q#AbO4&v44!0k z4Q#93Le6%TDI@}nxyEhu$v^EXhyG^=ikbYjwR1$_G<{@dv}ORHj0iE2l^DS(eyzkv zR9^K)F}e>MBSHZ*u|TLvXw}XneL9_%Ce1l1(W5uFAV zI^)buQEiw$6YV|dOzkvbD+P98P=0HcV~|ct zCCjbe)CpH z3md)=4eLZ-unEB9RtRU*(w`YXyx4zX9OamfuyuJ?L&h9rI_{{Nk)k{x{fdAZP8`6- z0fiRDOq9jyeZs2aZ0b#wLMKq)?#!-0L?+Du)6Zw z<`_m+pEN^t&IO#d=oKeotDY`l+X{xO)`sIOUs-9#_zwSvX&09dx7*Hl!LnZOK@5sC znWCrn{hpXg-RrfqR36B9^7E3R7gHWecFD;s5VywyG948J_Cc`X+E`qq0ii=tRpHEP zI-U@S@r7L)St2yA1dZrn>3p&O_z`Y1SZ_Dj?np^e5qkoV&op!{;+!R<5~9v}|H{d` z@^#;})F0Es$|nH(;&@CgPA4^9kLDCiY+~!fxv`|mY;T%#i42y&;Du08Ur6(4h}GU4 zqhI?mkyRRT)0l%%&@eux_t-gKPyM+LsR%3fzB)V1Ua?&+G|#7}!dM7?)X;T)E}+t zXy(q)9%=XqY88f+RQsRK43_}Uk>O7?3unfh#6j=k;7pPG&xBr((%keOm-mz8ayLPC*(2rx>0ivdq(5+G z(%9?C+ClAg+N3fn!PYJ2=+`UHsX&O z=Mc-j$OvmCm?XAxPdrJtZXCTb75F4t!=knjonIHnT+0wHYYV)&ySynBVfG+e7dMmU z&Bn?1`3eTjq=SK!v<`_zlHSP1HwIXM##?4CAssI+m`GNS?8-O2Xo=zl5Tcni8@Dw) z<2OmvND!Wyfv}iNO3oinLR4@!H;ukM;^yz)=-qcIW5!tWW3*Fq2u-!fd_odq^Jtuu z&HL3MuSG+cL=$?;DkZ=S$hb#>7ifs@^eAR9)LTLMWCOz#d1YbZyWljxH%JCKuXFl$@Ez&Tu9>6kF7v z7cy?!U+}GA-!^tNsM|tiC=<7CpIGX|k3J$@(Vn)|CT)pZoH0$)Wzf2bN7T|tpM@9V z6)P9&j`72hXxfC(UP>AyK7p)VEdh8cvGEBF%ZoYO@0yCK-uI2&Y?7WYFPgteBmk75 z0AtgVOY=qwcyd(HX5y8EB`I3cXFhr>^fU4W&`rxiOaNk%a04f@%pLy&mWPK-+d=Wo zstSQzC>kdx&99L8bVsJc<40Si4w4F&uZqfb!s>_8!Cc+6_4_A-zjPFd<)|rg_QOh* za0&3lZyIDV7_zy&!}5FHE2h2!1NbG?>pOQm%a%0>H=o8>=WE#Zi61w241-s9t^6LC z{v5=)2d-E$zJHz6x>EF`kJmsSqQH*>qIj##HX`?#GAgw8lmPjSHqji3aYxHNY`Lk` zn>9O1N{}iYR~m`LSywF}uAZm90QP$2yv_OKhR5e!8-1mzgcKM%RNMn+1|FVUi6IfN zFUFBYU?=@ZgI<8II(L&dJL5QN{JJYMT@}}f{zr(UW6AU*>26G~kZxA3rj-RKbQ^8@ z)T?FiXd$q4?!Ea?ASJI`1SNawgrI!7A+foQCNx?b73=59;td|{IvHH^K06+@m;5l~ zdzr$~sKWP5>P4+d_KVmrq%Zb}%}bjamM3S*C;1{I0Op07>p~!_De7k zIq7l5QwN-&YbJ0M9Hp2P;$VX?o{6IgkfP0g4$qaC$e7sP@7}6- zQHRZ+gI}aGLx<1Vp|!98|zwmd42_Ws=1;WQO9wqhpy2B(_r@C%2)Esc#f1;4DWwH zj|{&I9-ZUZjiW|IQljdC!ph#;L`6zaeio!A=E(p7-4dK%jpBa0B3w!R+0lk|jmC@O zw{YCJwp%{rZBm=o2EXQ9e;`~!Hvo~R5)SLqlkYVp1-#mE3Y;uuR|LA%p%8zqU2a*= z_mNV79TBpmwvd)^hjGE51Yg_xVF@%mhF|tdma)%|Oe(?cbB7=cW!H}(3Y##lW!TGM zO^y{THr(<`iX+?&&HUL>Y}8T`{9_?~A+%_NsYxjUN7l-eVPZ46-3QT`z?$R5h0E19 z^m{PUz$c)xE7a{Mw`f zpOrE$e3}3iZ8>;rA|#uO=?U24;zy}~IGQ%?vnYiomNBlJFoP@yX9kLEDo~?eWb$w# znlSIhglu;6_19Z5mS|dWV+~`Y^Y+vk`dW$&>G7XuZ?wwNlXCU1S(DHM`U@Ai42HY4O`U5({F!9!T2uV13O~Vq)R#jAK%}! z7Nsyx7D>T!>nT)GZ&8U7D=6Aw3Vi+AqMJK*td({3js-@8i-`tG7Pw$zCAA{uBdewi z5{a*9j9PJx{8K<`9QPZ!7>W_C*9I6QV03sX&}(mN_Li47d2>jcJ1O&PC|}17jL$;6 zCU50N*@Mf@Tm#AdDp+^;Zlb@Qxwr?18~(^t+trWhh6jI-hjdfCDbL?c&n0}v4uS*R zn2`$iH9e1KYoe}Nqy~>K8@XwTJGRuhZ3q3FrdbyRXv3StX z2%-DU+by(@HM=}YEphxf0=f9VYEo{AR;_>JmEK(K(=LdX1gV==?6BAbWm0JuZcUcRFT_b{y~a z!z>?e%e6eW5<$^BPYnTLW2H(jOPXY8!IVChz;BK#M`hjgd~_fbLlL_5P1knD2>2RK zSx2^~a5=!$T96@-r(b43biBkwqA~3tZJ}Q-Knb?hHszLf|2z84o=3mCppNkEh3#fX z+|}s=MlIUgSBYsxTkd;{Xdm@&cl0oG+$+vLE9tI_wg+X}56|$fnB+##3PQ zF=I7{$lg$!;&VQZUe=Zd$wvk5Fcd;3Z431avmaAa$XZob9ChVLMts<^_Qu)wG$*#> z;3*VHxjVFe3m%xJtg=mM)Uwn$*c6@9$zZf=(DLZS7DJ(^6BzWP-fyKlK7YYp3_}~U#rr# z=eo$sbhVaJsyv-%Out^vbcuPgx-&pHzHlv^E~$S=2(4m66sO}8q>*i8#0RH+-p^)E zl{9PnA(iujSpf0pR+#|Hh<71|Y^DH7re-F%yOIf=#luX4t3zrxU1&?waCQrc25IGtc_rWT;=)LF0 zuS9DGuSGG0X?tj;`Eo3O&GL_c_1_a)(|J`lGXcAjUN)8y7tDANYIie16wlf5rOI#T zpjb`Q2&m139-bv0YUx-S7rUZ*#!m;A*EXeFU&Tp2R=%x_*7`KNt=|U^>k|*9+#*gl zr z%ng3jcxUd0@oksjh_-y2FqMnv`JAJaRYLI!$7R@(0hL+3kWoiH8Qs;nmcm1+a^_un zIG5_Ly=zAOP3i(%VHAdu2zJ`65%}>C^ji9xcYZq-TO|;aPuo% zh4BBNHyZmESkm<6&n30_XPoG1t4n@k*R+Dzjo)oi3V+&bnpjWxV;u3y+WZCgkI$Cl zUvw7VchP)VsgY8idAH=e_q`T_ z4B5IWt%$3aGJ61B@a+yN4$#Bz2cXx^na?+qbL@HTZi}Q27$ld!s5OAc#ND046xp0Y zJ=tN3#}7hCD9mY4)k+h;)91^?#vX!zvDy*1b ziZeVy(+oUK`{UEK+suJXp<{@yi0K>@JfFHFsSIxUP~_|#g; zg{79P)I^bM6~wA2~5M~paYyotQowQ2OKQ|hemy7H=PP7Sy^DayB2-WU8`k*zpOXCI4!Ftk56YF z)vTv~-+Zu5m^TYpo-K(w+~lPp)*l!7&Dwq{!am&888ue@=(*S|#{Q7Z(?aYkmy=mH z_VHuRrC`TNa1iwHX2c-VBj64l)>Smy`Ek6n-zp{R6J{VD9@&qEAhvDh>ro+CaFlIe z$i$`TUIBp>5EOaZh*B@h)FQ6&sWO);uG0a*>UkCtC5o&fq2PVoZj z&?{0YW~7&PR+r_6yNM4`V+{hEQUTcY)gbo5)bT_!%Iu`lVd4zq?y@g3$!-+x$!0Tt zF8(inyjj?afam2m2WC>C<$3<1*^%3(a*T^xQtD>O)Lsrg7CRoVrd$Z8CWUBfhA$TG z(XC&9Kr=&i>cJu~A7qecJa8=<9L_60{e&^QUZ_TONm7Gz8Aoa593DA>PmUl{UqkB8 zZdn+~o3!gDCikLcdwi7Dq&nb^->W3Nvvqqf*Ceq0c(XE~jSqkP#P4|bqrb^VZ9hKu zuiq5g<)W8n&sIMG((Ec&!U9^9DkS}iIJ|YeCeEFP-X#+9dP#_pTHwvScm6@@9aNFG zU8(*LD6n+=mUUhock=iLq0%P+^D4HWNkjU1wS#$H{~p@xl7nTTzyfr0p8z5vb5tN{ zYf{@H+q&fvEp1zG*qYzvVqbw`IC5xtNq|xC(2(Abo0b5C?Guj;TUA(o0=Dvg5&mg$ zE+PC#-ZS4Y9pLw?D8HD(Uy?6#UMoSt>hkL^q1#n>#%Yeb6s!!0oapmR9kzGKHvOkO zM>ODT*5GZzcTUZ*$zYsCL3I;=d!Ez_+`9)JKh0!Mu z;#c8pyv;3-=811oP}_OF>~(RbSkB}jFQU_59P3|)utoa#m2f-e!2`AI;B;J2qNq03 zU^)Rrib6mn*~n--rTXq>W##*Q$k*9KUqziaT$tT1Z)B>1+uu&6lq}pYyO-kx$~(|Y zks^gA(h=HGYT)2-{saLE<*yogLP^47YO%5x7qqtQ7eT79qwt;1^2Uq6R^5iprr)uu z1_nl?t`8*pjbmRCZsP_V?HN@i=Ip<#Mt_m=L7-$aUkUN_9let)7Lrg#J+(shDEt7P zO_0k=&U>}dOA~6TcFp0Shael-za_xSsEefwo$J`uHnGdzA0#E)-9OkB+EHUu;}uzP ziM|O=E}OEd+tyX(i83WyKJz*Bbs=8eybUs2ceofiGqdk!z6=c4+gM8zq@z%hrKK)m znlmt}+Yp6U@=jc%K(?#AD)0}uoJTDk*BwlIz#pxB2>HJFI6f@i-ZU4_RzA0izi%0g z-nNnlnOsN^YTMPHLZ9xWm+P{*pRHIra~;Raf9z+Hkw6D?em+#-$kbW3r+_zb6$rI@ zt+TkiM8hH7RB|*WP}(ovGYPb%o-aldS5~%mnDm6u2Va%!-mSIG;A*LfB<{X0+VHia zeiN&sp{TAJeRVN@LB^UIL?6>v*w2dx{U8}HS|PV9LaKj9jyjQi7f8H$t2@@if1x&7 zrqTF3qJENB-z*-EALa%SsEZ+8xOdSvU{rOLpBD5hokluS zQ+0NoM?b3(l*iIQrncfx(sAP@*3hRuS?xv$?xtJ=rZj5=NaPR_yZvy&lkKEG8BIr3 zADq4xvOZh6)8fjvPMYB;^^@JyQw{Pz7?QaP;lXJ$vnE>Qwkzf$vQL~GjE>+{k4{0n zBujmT)hLd`4xV@|tG5#iwI^~JTjc*@(iZT!vn74Dg`fX5Ef*%~X`|Dxd19=Y4-HZJ za6URtP{LXJd*PmO{D+P>SZ=={EW7pTt38j?!=@NnOn$ zD^1#zh#!@b&=R|;rH#dN*zJca&mYd0LIX!rL0r=bj>%^*q0b!B2L~#3eDYuX+igU$ zxzOon4%slX6mV$_h!v+VzbYd}5Gy>tDmkodC*E%$Q@2YoA*0e)BlF7Wm*C~(cxA^u zN0;YriK)c7=c?|wWlIIg%8%BYmCmnjx3vjubDDBld#TnJLa>#r4msv7*ZXVD5Y<1F zx4Ak!erFh${?o+;SC~!7aSFPn!>3`IYJ5#Epx8@$(Bo0<~ZuQ4e z%+z=u{Tkm!UpXdEzS1kTi>aa38|sV+y!IsEiE#MD_)6cEYEND?p>Im9;B0{>GA=ay z;`=ZQ(&k*z#ZBan@v-M`*Zn7eP5R!qiR`QcRPKJ!=7WCH=~4-6-wlr9QGo>ytL4p@ zyfEKC*B8^?m=YtuK)T`X6dmu5^?Up^eS>g(iEbNhd`r$4<6zt16dZEl?0NNwMZB;P zrd*RU|1e!HOdZCtc#5lXxFg8`o;z_(z<;p4C(VNqUuEp1PnoO$kNOPVK}* zj$sMC)@n+*=j>p6knn3M;q=@DU=kLYexv* z;TUFGbf$P2^IY-u`FX|RSAu0!fkj2FcX$dIQ}4W#_e>huC6YFnj0azv56(JxI;sR1 zwTI27s?P2w5veU48hU#g29jm3W_{Ag;q|?_qumPVP~4nZ3S$~h5@_y7K-0vc)J6m% z^RSq4C^O%d>TuL!6FY8=eF`9RvfUT8kU6}+KWrGKZ)RG4K=acnk zEVT)hl+X{N^bayL?(1R*3Ayjrc><*W^yjXMJ^`D%W=G$VK>B3_ycVfbPLrLC@q)pM zg5^qBh=uty0K|r%&u2J4MSqxt))v`yIZV!EEQIOtw^Lxq7ZevvYm>5A(mNEG$dPyi zp?we2%b>N6Gw0h7a=D=2l;NN8jKLTM$caCD3ABU|_5}DUF3@x5^U^QZLqzs6GI%ck zT%rFK^)v}KU1;z4%>$e4?xq*vncf!3iFtnSAfEdHj#*j0^h9gZ^r; zwz_ZNaa-?&O$GOaZw~na%;%b|q3rpHxRaoNd2}6h%UXLYhE&%XvRIZ=_L#tW&_7ps zeQuwiyJl&e>q3MrI|HZbbq<9GiS&hxtly7=GE9clKudfEBY1Kj7Z}&~PD*w|B!jhb zGnoj}kH7$tH1{68egB-F-R1WHi4jCV_{}uq#K?UQcP62h?1#xe`%>$Zny?G;^C^xG zjlFx;-;J6a?@ZI;1@EXnwh}2S3trg-$T zoWwqTIY!2LTcwoVkXbl|aW0~4yLsHvEBjxHM*9ttU&os-A9Wt~SGR*oEnhx3v=mpQ zxXj;&d`50wmDHqKWMETex*QX_?8J+|UGY@Y!K}hlXJ?57#6c{V>|aDytVoQ}$ZU#> zyNp&Jesff0mD!{mGvLIRx$GSJA8d_f7ijHMyT*D#%rsv<_OyJPq^wMNJOZj}D9?~!~)!R*LCc!g;of-ub1|=s9 z$-*0wHD$+Qhc`>@dikoso`8IGy7)K-%+#qp0z@>*JFlWCV$qsjg=&*V=WeM!yb`Pj zSpvJ-1K7pmp3}oTVbWF;X^3zO`9rIEQbPUVCdu;vz2X_?6j(t&g|o5^n0a zQTB-!<&WsJMhDq4_%}uyC3n4RcQVT`_fjmv4?EquZ5!e3&ykr2+&weE;zPp zX8w2+r&nvKm+2ryuNRk5CU0a{V&QaO$EW4t+w|RZ=rr@G-jVsFU2SaOH3vA8N+KF0 zbb7E+|4i~cICG}E@v0cO;GHJqT{ldDIrQ*pt=a&?-gYxv#N(I(9zwy+^C@HDB+E%1^@GV9>o>}Y_WtP* zx|qV41N15dI>QV1A-buIqNeGxKM%3}H*(jXgyXN!=)P3F-1bm47V0?baDQ!22tjm- zL77hE9j!UMC*{24r!v;#nBqpmkj=-atuM-P7g)jFEyl4a^{NeXrLF51lq_XQD;X>+ zyVNYoIEWI&nH!OJg}oN~a+)XJkYG7OPpE8aqdsNi8~nz_ptI$> zRIyYmvmRc37U5 zOi7nWg*zMe?9RG-0Z!ZPZ@<2(z3NZj$rR_OMLrZ&B^4RwMng4xxIW@ZZLfy!tBv1& z$s1H;;-u+44`^9UU=42QtumVV$rrg#&yNmr`sQ&KP&&gZ9iF9x|FObJ_#~x?;bg^F z@1U=&OsTrWFZYN4WdL>VL-r}!`N9jb{#fG|YkP~#sB^Yl%#5?KM}99$B@t*SQ!$f_s7i*gtYdi^#`)m zhmZYz{;vyPpF1Gzu6m=McaS3#@lNff`A)D+h#KaY)&={-mN1t1X3?I&cJ5hRY^>uY zWufbLOFy%UM(a|s&Lb`B+Sfva;zaxjErz0JM%Q`IGk zqs|Q9?tYzhu&`!1eEMRoZ`9Kw>zw`S@E%R-qBY-`*|KgM#kWQ##9^GN6ccc01O7?y5muyBg;ZJ$R?}D? zx1x14G3*45(#SYW8f_H@9DAscr3~}cr3l}JZb{wWic-j9po%yV=@z!M2BaG6nL;6=j4iAtfV;o9fD?<`PBbVLe_fq?Ev%t$DLJQhYKyCX4kYa`~{ zLSGh34vp`dp6-8|-`YcKnZNK6Z**&P~b z^h&G5GYvMX3`+~0ku)~v1!r$zO6mu{d~)qDu?9%XQd2ZLj3)=N}e z<|2Ld&!ZU4xSAxF;kYA5o?s|?^hmc4%jl_CUO|oU!WH~KbdV7m) zJpmOfd2fRwCxx1kg=mm{yoT;d&Vr6cRHR)$Go2KZ*Bih}o*xoi&QETXwX?gJA8EnA z3;PU$YnsLXDCzE;U(})zY}NZo`%{X>dfMXL#{2q{tnZh(Xw?ZnBVn(CW*exnMX0q= zF5#7+!{;8uL{tVbwD@8gdXu=Ljj&`%7O(YVg(&r=KzdAQ=r_y^RtNW!kH+iVbTmTa z=%JFxk`Q9XiMT?{$<&FqldEH!Q$z% zvXn5HwHoR&BHLOwNoV&K5yR~)9?u3I+|w(5W0ae5N9VRHBdcTe`mKn|*EM8{4AT?$uq(^%H=GabsG(cr4IJ#*}h{UPR*uYM!Q- zbtS+*3CT{n$fZiqO_NyK8EM?8b&DGFjrIc-+l?k7(YGL0DWQg0YSHGOY-c7i*pzS& zQqjg&eYDo|3~(kNCvR2`M%mLI%hjCw!DGHN-_