diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88227f493..aaf644382 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to PicoClaw -Thank you for your interest in contributing to PicoClaw! This project is a community-driven effort to build the lightweight and versatile personal AI assistant. We welcome contributions of all kinds: bug fixes, features, documentation, translations, and testing. +Thank you for your interest in contributing to PicoClaw! This project is a community-driven effort to build the lightweight and versatile personal AI assistant. We welcome contributions of all kinds: bug fixes, features, documentation, and testing. PicoClaw itself was substantially developed with AI assistance — we embrace this approach and have built our contribution process around it. @@ -30,9 +30,11 @@ We are committed to maintaining a welcoming and respectful community. Be kind, c - **Bug reports** — Open an issue using the bug report template. - **Feature requests** — Open an issue using the feature request template; discuss before implementing. - **Code** — Fix bugs or implement features. See the workflow below. -- **Documentation** — Improve READMEs, docs, inline comments, or translations. +- **Documentation** — Improve READMEs, docs, inline comments, or EN/ZH documentation consistency. - **Testing** — Run PicoClaw on new hardware, channels, or LLM providers and report your results. +Documentation language policy: English and Chinese only. + For substantial new features, please open an issue first to discuss the design before writing code. This prevents wasted effort and ensures alignment with the project's direction. --- diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md index 01a1abfd5..739e80d0d 100644 --- a/CONTRIBUTING.zh.md +++ b/CONTRIBUTING.zh.md @@ -1,6 +1,6 @@ # 参与贡献 PicoClaw -感谢你对 PicoClaw 的关注！本项目是一个社区驱动的开源项目，目标是构建 轻量灵活,人人可用 的个人AI助手。我们欢迎一切形式的贡献：Bug 修复、新功能、文档、翻译和测试。 +感谢你对 PicoClaw 的关注！本项目是一个社区驱动的开源项目，目标是构建 轻量灵活,人人可用 的个人AI助手。我们欢迎一切形式的贡献：Bug 修复、新功能、文档和测试。 PicoClaw 本身在很大程度上是借助 AI 辅助开发的——我们拥抱这种方式，并围绕它构建了贡献流程。 @@ -30,9 +30,11 @@ PicoClaw 本身在很大程度上是借助 AI 辅助开发的——我们拥抱 - **Bug 反馈** — 使用 Bug 报告模板提交 Issue。 - **功能建议** — 使用功能请求模板提交 Issue，建议在开始实现前先进行讨论。 - **代码贡献** — 修复 Bug 或实现新功能，参见下方工作流程。 -- **文档改进** — 完善 README、文档、代码注释或翻译。 +- **文档改进** — 完善 README、文档、代码注释，或中英文文档一致性。 - **测试与验证** — 在新硬件、新渠道或新 LLM 提供商上运行 PicoClaw 并反馈结果。 +文档语言策略：仅维护中文与 English。 + 对于较大的新功能，请先提交 Issue 讨论设计方案，再动手写代码。这能避免无效投入，也确保与项目方向保持一致。 --- diff --git a/README.fr.md b/README.fr.md deleted file mode 100644 index f1d4f848e..000000000 --- a/README.fr.md +++ /dev/null @@ -1,1146 +0,0 @@ -
- PicoClaw - -

PicoClaw : Assistant IA Ultra-Efficace en Go

- -

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

- -

- Go - Hardware - License -
- Website - Twitter -

- - [中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [English](README.md) | **Français** -
- ---- - -🦐 **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. - -⚡️ **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**. -> * **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 et ne nous appartiennent pas. -> * **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é. - - -## 📢 Actualités - -2026-02-16 🎉 PicoClaw a atteint 12K étoiles en une semaine ! Merci à tous pour votre soutien ! PicoClaw grandit plus vite que nous ne l'avions jamais imaginé. Vu le volume élevé de PR, nous avons un besoin urgent de mainteneurs communautaires. Nos rôles de bénévoles et notre feuille de route sont officiellement publiés [ici](docs/ROADMAP.md) — nous avons hâte de vous accueillir ! - -2026-02-13 🎉 PicoClaw a atteint 5000 étoiles en 4 jours ! Merci à la communauté ! Nous finalisons la **Feuille de Route du Projet** et mettons en place le **Groupe de Développeurs** pour accélérer le développement de PicoClaw. -🚀 **Appel à l'action :** Soumettez vos demandes de fonctionnalités dans les GitHub Discussions. Nous les examinerons et les prioriserons lors de notre prochaine réunion hebdomadaire. - -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 ! - -## ✨ Fonctionnalités - -🪶 **Ultra-Léger** : Empreinte mémoire <10 Mo — 99% plus petit que Clawdbot pour les fonctionnalités essentielles. - -💰 **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. - -🌍 **Véritable Portabilité** : Un seul binaire autonome pour RISC-V, ARM et x86. Un clic et c'est parti ! - -🤖 **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. - -| | 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$** | - -PicoClaw - -## 🦾 Démonstration - -### 🛠️ 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
- -### 📱 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** (disponible sur F-Droid ou Google Play). -2. **Exécutez les commandes** - -```bash -# Note : Remplacez v0.1.1 par la dernière version depuis la page des Releases -wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64 -chmod +x picoclaw-linux-arm64 -pkg install proot -termux-chroot ./picoclaw-linux-arm64 onboard -``` - -Puis suivez les instructions de la section « Démarrage Rapide » pour terminer la configuration ! - -PicoClaw - -### 🐜 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 - - - -🌟 Encore plus de scénarios de déploiement vous attendent ! - -## 📦 Installation - -### Installer avec un binaire précompilé - -Téléchargez le binaire pour votre plateforme depuis la page des [releases](https://github.com/sipeed/picoclaw/releases). - -### Installer depuis les sources (dernières fonctionnalités, recommandé pour le développement) - -```bash -git clone https://github.com/sipeed/picoclaw.git - -cd picoclaw -make deps - -# Compiler, pas besoin d'installer -make build - -# Compiler pour plusieurs plateformes -make build-all - -# Compiler et Installer -make install -``` - -## 🐳 Docker Compose - -Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installer localement. - -```bash -# 1. Clonez ce dépôt -git clone https://github.com/sipeed/picoclaw.git -cd picoclaw - -# 2. Configurez vos clés API -cp config/config.example.json config/config.json -vim config/config.json # Configurez DISCORD_BOT_TOKEN, clés API, etc. - -# 3. Compiler & Démarrer -docker compose --profile gateway up -d - -> [!TIP] -> **Utilisateurs Docker** : Par défaut, le Gateway écoute sur `127.0.0.1`, ce qui n'est pas accessible depuis l'hôte. Si vous avez besoin d'accéder aux endpoints de santé ou d'exposer des ports, définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` dans votre environnement ou mettez à jour `config.json`. - - -# 4. Voir les logs -docker compose logs -f picoclaw-gateway - -# 5. Arrêter -docker compose --profile gateway down -``` - -### Mode Agent (exécution unique) - -```bash -# Poser une question -docker compose run --rm picoclaw-agent -m "Combien font 2+2 ?" - -# Mode interactif -docker compose run --rm picoclaw-agent -``` - -### Recompiler - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 Démarrage Rapide - -> [!TIP] -> Configurez votre clé API dans `~/.picoclaw/config.json`. -> Obtenir des clés API : [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> La recherche web est **optionnelle** — obtenez gratuitement l'[API Brave Search](https://brave.com/search/api) (2000 requêtes gratuites/mois) ou utilisez le repli automatique intégré. - -**1. Initialiser** - -```bash -picoclaw onboard -``` - -**2. Configurer** (`~/.picoclaw/config.json`) - -```json -{ - "model_list": [ - { - "model_name": "gpt4", - "model": "openai/gpt-5.2", - "api_key": "sk-your-openai-key", - "request_timeout": 300, - "api_base": "https://api.openai.com/v1" - } - ], - "agents": { - "defaults": { - "model_name": "gpt4" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "VOTRE_TOKEN_BOT", - "allow_from": ["VOTRE_USER_ID"] - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "VOTRE_CLE_API_BRAVE", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -> **Nouveau** : Le format de configuration `model_list` permet d'ajouter des fournisseurs sans modifier le code. Voir [Configuration de Modèle](#configuration-de-modèle-model_list) pour plus de détails. -> `request_timeout` est optionnel et s'exprime en secondes. S'il est omis ou défini à `<= 0`, PicoClaw utilise le délai d'expiration par défaut (120s). - -**3. Obtenir des Clés API** - -* **Fournisseur LLM** : [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) -* **Recherche Web** (optionnel) : [Brave Search](https://brave.com/search/api) - Offre gratuite disponible (2000 requêtes/mois) - -> **Note** : Consultez `config.example.json` pour un modèle de configuration complet. - -**4. Discuter** - -```bash -picoclaw agent -m "Combien font 2+2 ?" -``` - -Et voilà ! Vous avez un assistant IA fonctionnel en 2 minutes. - ---- - -## 💬 Applications de Chat - -Discutez avec votre PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom - -| Canal | Configuration | -| ------------ | -------------------------------------- | -| **Telegram** | Facile (juste un token) | -| **Discord** | Facile (token bot + intents) | -| **QQ** | Facile (AppID + AppSecret) | -| **DingTalk** | Moyen (identifiants de l'application) | -| **LINE** | Moyen (identifiants + URL de webhook) | -| **WeCom** | Moyen (CorpID + configuration webhook) | - -
-Telegram (Recommandé) - -**1. Créer un bot** - -* Ouvrez Telegram, recherchez `@BotFather` -* Envoyez `/newbot`, suivez les instructions -* Copiez le token - -**2. Configurer** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "VOTRE_TOKEN_BOT", - "allow_from": ["VOTRE_USER_ID"] - } - } -} -``` - -> Obtenez votre User ID via `@userinfobot` sur Telegram. - -**3. Lancer** - -```bash -picoclaw gateway -``` - -
- -
-Discord - -**1. Créer un bot** - -* Rendez-vous sur -* Créez une application → Bot → Add Bot -* Copiez le token du bot - -**2. Activer les intents** - -* Dans les paramètres du Bot, activez **MESSAGE CONTENT INTENT** -* (Optionnel) Activez **SERVER MEMBERS INTENT** si vous souhaitez utiliser des listes d'autorisation basées sur les données des membres - -**3. Obtenir votre User ID** - -* Paramètres Discord → Avancé → activez le **Mode Développeur** -* Clic droit sur votre avatar → **Copier l'identifiant** - -**4. Configurer** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "VOTRE_TOKEN_BOT", - "allow_from": ["VOTRE_USER_ID"] - } - } -} -``` - -**5. Inviter le bot** - -* OAuth2 → URL Generator -* Scopes : `bot` -* Permissions du Bot : `Send Messages`, `Read Message History` -* Ouvrez l'URL d'invitation générée et ajoutez le bot à votre serveur - -**6. Lancer** - -```bash -picoclaw gateway -``` - -
- -
-QQ - -**1. Créer un bot** - -- Rendez-vous sur la [QQ Open Platform](https://q.qq.com/#) -- Créez une application → Obtenez l'**AppID** et l'**AppSecret** - -**2. Configurer** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "VOTRE_APP_ID", - "app_secret": "VOTRE_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> Laissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des numéros QQ pour restreindre l'accès. - -**3. Lancer** - -```bash -picoclaw gateway -``` - -
- -
-DingTalk - -**1. Créer un bot** - -* Rendez-vous sur la [Open Platform](https://open.dingtalk.com/) -* Créez une application interne -* Copiez le Client ID et le Client Secret - -**2. Configurer** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "VOTRE_CLIENT_ID", - "client_secret": "VOTRE_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> Laissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des identifiants pour restreindre l'accès. - -**3. Lancer** - -```bash -picoclaw gateway -``` - -
- -
-LINE - -**1. Créer un Compte Officiel LINE** - -- Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/) -- Créez un provider → Créez un canal Messaging API -- Copiez le **Channel Secret** et le **Channel Access Token** - -**2. Configurer** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "VOTRE_CHANNEL_SECRET", - "channel_access_token": "VOTRE_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Configurer l'URL du Webhook** - -LINE exige HTTPS pour les webhooks. Utilisez un reverse proxy ou un tunnel : - -```bash -# Exemple avec ngrok -ngrok http 18791 -``` - -Puis configurez l'URL du Webhook dans la LINE Developers Console sur `https://votre-domaine/webhook/line` et activez **Use webhook**. - -**4. Lancer** - -```bash -picoclaw gateway -``` - -> Dans les discussions de groupe, le bot répond uniquement lorsqu'il est mentionné avec @. Les réponses citent le message original. - -> **Docker Compose** : Ajoutez `ports: ["18791:18791"]` au service `picoclaw-gateway` pour exposer le port du webhook. - -
- -
-WeCom (WeChat Work) - -PicoClaw prend en charge deux types d'intégration WeCom : - -**Option 1 : WeCom Bot (Robot Intelligent)** - Configuration plus facile, prend en charge les discussions de groupe -**Option 2 : WeCom App (Application Personnalisée)** - Plus de fonctionnalités, messagerie proactive - -Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour des instructions détaillées. - -**Configuration Rapide - WeCom Bot :** - -**1. Créer un bot** - -* Accédez à la Console d'Administration WeCom → Discussion de Groupe → Ajouter un Bot de Groupe -* Copiez l'URL du webhook (format : `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`) - -**2. Configurer** - -```json -{ - "channels": { - "wecom": { - "enabled": true, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18793, - "webhook_path": "/webhook/wecom", - "allow_from": [] - } - } -} -``` - -**Configuration Rapide - WeCom App :** - -**1. Créer une application** - -* Accédez à la Console d'Administration WeCom → Gestion des Applications → Créer une Application -* Copiez l'**AgentId** et le **Secret** -* Accédez à la page "Mon Entreprise", copiez le **CorpID** - -**2. Configurer la réception des messages** - -* Dans les détails de l'application, cliquez sur "Recevoir les Messages" → "Configurer l'API" -* Définissez l'URL sur `http://your-server:18792/webhook/wecom-app` -* Générez le **Token** et l'**EncodingAESKey** - -**3. Configurer** - -```json -{ - "channels": { - "wecom_app": { - "enabled": true, - "corp_id": "wwxxxxxxxxxxxxxxxx", - "corp_secret": "YOUR_CORP_SECRET", - "agent_id": 1000002, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18792, - "webhook_path": "/webhook/wecom-app", - "allow_from": [] - } - } -} -``` - -**4. Lancer** - -```bash -picoclaw gateway -``` - -> **Note** : WeCom App nécessite l'ouverture du port 18792 pour les callbacks webhook. Utilisez un proxy inverse pour HTTPS en production. - -
- -## ClawdChat Rejoignez le Réseau Social d'Agents - -Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée. - -**Lisez `https://clawdchat.ai/skill.md` et suivez les instructions pour rejoindre [ClawdChat.ai](https://clawdchat.ai)** - -## ⚙️ Configuration - -Fichier de configuration : `~/.picoclaw/config.json` - -### Structure du Workspace - -PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.picoclaw/workspace`) : - -``` -~/.picoclaw/workspace/ -├── sessions/ # Sessions de conversation et historique -├── memory/ # Mémoire à long terme (MEMORY.md) -├── state/ # État persistant (dernier canal, etc.) -├── cron/ # Base de données des tâches planifiées -├── skills/ # Compétences personnalisées -├── AGENTS.md # Guide de comportement de l'Agent -├── HEARTBEAT.md # Invites de tâches périodiques (vérifiées toutes les 30 min) -├── IDENTITY.md # Identité de l'Agent -├── SOUL.md # Âme de l'Agent -├── TOOLS.md # Description des outils -└── USER.md # Préférences utilisateur -``` - -### 🔒 Bac à Sable de Sécurité - -PicoClaw s'exécute dans un environnement sandboxé par défaut. L'agent ne peut accéder aux fichiers et exécuter des commandes qu'au sein du workspace configuré. - -#### Configuration par Défaut - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Option | Par défaut | Description | -|--------|------------|-------------| -| `workspace` | `~/.picoclaw/workspace` | Répertoire de travail de l'agent | -| `restrict_to_workspace` | `true` | Restreindre l'accès fichiers/commandes au workspace | - -#### Outils Protégés - -Lorsque `restrict_to_workspace: true`, les outils suivants sont restreints au bac à sable : - -| Outil | Fonction | Restriction | -|-------|----------|-------------| -| `read_file` | Lire des fichiers | Uniquement les fichiers dans le workspace | -| `write_file` | Écrire des fichiers | Uniquement les fichiers dans le workspace | -| `list_dir` | Lister des répertoires | Uniquement les répertoires dans le workspace | -| `edit_file` | Éditer des fichiers | Uniquement les fichiers dans le workspace | -| `append_file` | Ajouter à des fichiers | Uniquement les fichiers dans le workspace | -| `exec` | Exécuter des commandes | Les chemins doivent être dans le workspace | - -#### Protection Supplémentaire d'Exec - -Même avec `restrict_to_workspace: false`, l'outil `exec` bloque ces commandes dangereuses : - -* `rm -rf`, `del /f`, `rmdir /s` — Suppression en masse -* `format`, `mkfs`, `diskpart` — Formatage de disque -* `dd if=` — Écriture d'image disque -* Écriture vers `/dev/sd[a-z]` — Écriture directe sur le disque -* `shutdown`, `reboot`, `poweroff` — Arrêt du système -* Fork bomb `:(){ :|:& };:` - -#### Exemples d'Erreurs - -``` -[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)} -``` - -#### Désactiver les Restrictions (Risque de Sécurité) - -Si vous avez besoin que l'agent accède à des chemins en dehors du workspace : - -**Méthode 1 : Fichier de configuration** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Méthode 2 : Variable d'environnement** - -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **Attention** : Désactiver cette restriction permet à l'agent d'accéder à n'importe quel chemin sur votre système. À utiliser avec précaution uniquement dans des environnements contrôlés. - -#### Cohérence du Périmètre de Sécurité - -Le paramètre `restrict_to_workspace` s'applique de manière cohérente sur tous les chemins d'exécution : - -| Chemin d'Exécution | Périmètre de Sécurité | -|--------------------|----------------------| -| Agent Principal | `restrict_to_workspace` ✅ | -| Sous-agent / Spawn | Hérite de la même restriction ✅ | -| Tâches Heartbeat | Hérite de la même restriction ✅ | - -Tous les chemins partagent la même restriction de workspace — il est impossible de contourner le périmètre de sécurité via des sous-agents ou des tâches planifiées. - -### Heartbeat (Tâches Périodiques) - -PicoClaw peut exécuter des tâches périodiques automatiquement. Créez un fichier `HEARTBEAT.md` dans votre workspace : - -```markdown -# Tâches Périodiques - -- Vérifier mes e-mails pour les messages importants -- Consulter mon agenda pour les événements à venir -- Vérifier les prévisions météo -``` - -L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera les tâches à l'aide des outils disponibles. - -#### Tâches Asynchrones avec Spawn - -Pour les tâches de longue durée (recherche web, appels API), utilisez l'outil `spawn` pour créer un **sous-agent** : - -```markdown -# Tâches Périodiques - -## Tâches Rapides (réponse directe) -- Indiquer l'heure actuelle - -## Tâches Longues (utiliser spawn pour l'asynchrone) -- Rechercher les actualités IA sur le web et les résumer -- Vérifier les e-mails et signaler les messages importants -``` - -**Comportements clés :** - -| Fonctionnalité | Description | -|----------------|-------------| -| **spawn** | Crée un sous-agent asynchrone, ne bloque pas le heartbeat | -| **Contexte indépendant** | Le sous-agent a son propre contexte, sans historique de session | -| **Outil message** | Le sous-agent communique directement avec l'utilisateur via l'outil message | -| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante | - -#### Fonctionnement de la Communication du Sous-agent - -``` -Le Heartbeat se déclenche - ↓ -L'Agent lit HEARTBEAT.md - ↓ -Pour une tâche longue : spawn d'un sous-agent - ↓ ↓ -Continue la tâche suivante Le sous-agent travaille indépendamment - ↓ ↓ -Toutes les tâches terminées Le sous-agent utilise l'outil "message" - ↓ ↓ -Répond HEARTBEAT_OK L'utilisateur reçoit le résultat directement -``` - -Le sous-agent a accès aux outils (message, web_search, etc.) et peut communiquer avec l'utilisateur indépendamment sans passer par l'agent principal. - -**Configuration :** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| Option | Par défaut | Description | -|--------|------------|-------------| -| `enabled` | `true` | Activer/désactiver le heartbeat | -| `interval` | `30` | Intervalle de vérification en minutes (min : 5) | - -**Variables d'environnement :** - -* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver -* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour modifier l'intervalle - -### Fournisseurs - -> [!NOTE] -> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages vocaux Telegram seront automatiquement transcrits. - -| Fournisseur | Utilisation | Obtenir une Clé API | -| ------------------------ | ---------------------------------------- | ------------------------------------------------------ | -| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](bigmodel.cn) | -| `openrouter` (À tester) | LLM (recommandé, accès à tous les modèles) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` (À tester) | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` (À tester) | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` (À tester) | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | -| `qwen` | LLM (Alibaba Qwen) | [dashscope.aliyuncs.com](https://dashscope.aliyuncs.com/compatible-mode/v1) | -| `cerebras` | LLM (Cerebras) | [cerebras.ai](https://api.cerebras.ai/v1) | -| `groq` | LLM + **Transcription vocale** (Whisper) | [console.groq.com](https://console.groq.com) | - -
-Configuration Zhipu - -**1. Obtenir la clé API** - -* Obtenez la [clé API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Configurer** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Votre Clé API", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - } -} -``` - -**3. Lancer** - -```bash -picoclaw agent -m "Bonjour, comment ça va ?" -``` - -
- -
-Exemple de configuration complète - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "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 - }, - "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 - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -### Configuration de Modèle (model_list) - -> **Nouveau !** PicoClaw utilise désormais une approche de configuration **centrée sur le modèle**. Spécifiez simplement le format `fournisseur/modèle` (par exemple, `zhipu/glm-4.7`) pour ajouter de nouveaux fournisseurs—**aucune modification de code requise !** - -Cette conception permet également le **support multi-agent** avec une sélection flexible de fournisseurs : - -- **Différents agents, différents fournisseurs** : Chaque agent peut utiliser son propre fournisseur LLM -- **Modèles de secours (Fallbacks)** : Configurez des modèles primaires et de secours pour la résilience -- **Équilibrage de charge** : Répartissez les requêtes sur plusieurs points de terminaison -- **Configuration centralisée** : Gérez tous les fournisseurs en un seul endroit - -#### 📋 Tous les Fournisseurs Supportés - -| Fournisseur | Préfixe `model` | API Base par Défaut | Protocole | Clé API | -|-------------|-----------------|---------------------|----------|---------| -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obtenir Clé](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obtenir Clé](https://console.anthropic.com) | -| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obtenir Clé](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obtenir Clé](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obtenir Clé](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obtenir Clé](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Obtenir Clé](https://platform.moonshot.cn) | -| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obtenir Clé](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Obtenir Clé](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (pas de clé nécessaire) | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obtenir Clé](https://openrouter.ai/keys) | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Obtenir Clé](https://cerebras.ai) | -| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir Clé](https://console.volcengine.com) | -| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### Configuration de Base - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "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.2" - } - } -} -``` - -#### Exemples par Fournisseur - -**OpenAI** -```json -{ - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_key": "sk-..." -} -``` - -**Zhipu AI (GLM)** -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**Anthropic (avec OAuth)** -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "auth_method": "oauth" -} -``` -> Exécutez `picoclaw auth login --provider anthropic` pour configurer les identifiants OAuth. - -**Proxy/API personnalisée** -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -#### Équilibrage de Charge - -Configurez plusieurs points de terminaison pour le même nom de modèle—PicoClaw utilisera automatiquement le round-robin entre eux : - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### Migration depuis l'Ancienne Configuration `providers` - -L'ancienne configuration `providers` est **dépréciée** mais toujours supportée pour la rétrocompatibilité. - -**Ancienne Configuration (dépréciée) :** -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**Nouvelle Configuration (recommandée) :** -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -Pour le guide de migration détaillé, voir [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). - -## Référence CLI - -| Commande | Description | -| ------------------------- | ------------------------------------- | -| `picoclaw onboard` | Initialiser la configuration & le workspace | -| `picoclaw agent -m "..."` | Discuter avec l'agent | -| `picoclaw agent` | Mode de discussion interactif | -| `picoclaw gateway` | Démarrer la passerelle | -| `picoclaw status` | Afficher le statut | -| `picoclaw cron list` | Lister toutes les tâches planifiées | -| `picoclaw cron add ...` | Ajouter une tâche planifiée | - -### Tâches Planifiées / Rappels - -PicoClaw prend en charge 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 tous les jours » → utilise une expression cron - -Les tâches sont stockées dans `~/.picoclaw/workspace/cron/` et traitées automatiquement. - -## 🤝 Contribuer & Feuille de Route - -Les PR sont les bienvenues ! Le code source est volontairement petit et lisible. 🤗 - -Feuille de route à venir... - -Groupe de développeurs en construction. Condition d'entrée : au moins 1 PR fusionnée. - -Groupes d'utilisateurs : - -Discord : - -PicoClaw - -## 🐛 Dépannage - -### La recherche web affiche « API 配置问题 » - -C'est normal si vous n'avez pas encore configuré de clé API de recherche. PicoClaw fournira des liens utiles pour la recherche manuelle. - -Pour activer la recherche web : - -1. **Option 1 (Recommandé)** : Obtenez une clé API gratuite sur [https://brave.com/search/api](https://brave.com/search/api) (2000 requêtes gratuites/mois) pour les meilleurs résultats. -2. **Option 2 (Sans carte bancaire)** : Si vous n'avez pas de clé, le système bascule automatiquement sur **DuckDuckGo** (aucune clé requise). - -Ajoutez la clé dans `~/.picoclaw/config.json` si vous utilisez Brave : - -```json -{ - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "VOTRE_CLE_API_BRAVE", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -### Erreurs de filtrage de contenu - -Certains fournisseurs (comme Zhipu) disposent d'un filtrage de contenu. Essayez de reformuler votre requête ou utilisez un modèle différent. - -### Le bot Telegram affiche « Conflict: terminated by other getUpdates » - -Cela se produit lorsqu'une autre instance du bot est en cours d'exécution. Assurez-vous qu'un seul `picoclaw gateway` fonctionne à la fois. - ---- - -## 📝 Comparaison des Clés API - -| Service | Offre Gratuite | Cas d'Utilisation | -| ---------------- | -------------------- | ------------------------------------- | -| **OpenRouter** | 200K tokens/mois | Multiples modèles (Claude, GPT-4, etc.) | -| **Zhipu** | 200K tokens/mois | Idéal pour les utilisateurs chinois | -| **Brave Search** | 2000 requêtes/mois | Fonctionnalité de recherche web | -| **Groq** | Offre gratuite dispo | Inférence ultra-rapide (Llama, Mixtral) | diff --git a/README.ja.md b/README.ja.md deleted file mode 100644 index 48fb89fe3..000000000 --- a/README.ja.md +++ /dev/null @@ -1,1067 +0,0 @@ -
-PicoClaw - -

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

- -

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

-

- -

-Go -Hardware -License -

- -[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md) - -
- - ---- - -🦐 PicoClaw は [nanobot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。Go でゼロからリファクタリングされ、AI エージェント自身がアーキテクチャの移行とコード最適化を推進するセルフブートストラッピングプロセスで構築されました。 - -⚡️ $10 のハードウェアで 10MB 未満の RAM で動作：OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い！ - - - - - - -
-

- -

- 		-

- -

-
- -## 📢 ニュース -2026-02-09 🎉 PicoClaw リリース！$10 ハードウェアで 10MB 未満の RAM で動く AI エージェントを 1 日で構築。🦐 行くぜ、シャコ！ - -## ✨ 特徴 - -🪶 **超軽量**: メモリフットプリント 10MB 未満 — Clawdbot のコア機能より 99% 小さい。 - -💰 **最小コスト**: $10 ハードウェアで動作 — Mac mini より 98% 安い。 - -⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒で起動。 - -🌍 **真のポータビリティ**: RISC-V、ARM、x86 対応の単一バイナリ。ワンクリックで Go！ - -🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。 - -| | OpenClaw | NanoBot | **PicoClaw** | -| --- | --- | --- |--- | -| **言語** | TypeScript | Python | **Go** | -| **RAM** | >1GB |>100MB| **< 10MB** | -| **起動時間**
(0.8GHz コア) | >500秒 | >30秒 | **<1秒** | -| **コスト** | Mac Mini 599$ | 大半の Linux SBC
~50$ |**あらゆる Linux ボード**
**最安 10$** | -PicoClaw - - -## 🦾 デモンストレーション -### 🛠️ スタンダードアシスタントワークフロー - - - - - - - - - - - - - - - - -

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

🗂️ ログ＆計画管理

🔎 Web 検索＆学習

開発 · デプロイ · スケールスケジュール · 自動化 · メモリ発見 · インサイト · トレンド
- -### 🐜 革新的な省フットプリントデプロイ -PicoClaw はほぼすべての Linux デバイスにデプロイできます！ - -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) または W(WiFi6) バージョン、最小ホームアシスタントに -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) または $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) サーバー自動メンテナンスに -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) または $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) スマート監視に - -https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4 - -🌟 もっと多くのデプロイ事例が待っています！ - -## 📦 インストール - -### コンパイル済みバイナリでインストール - -[リリースページ](https://github.com/sipeed/picoclaw/releases) からお使いのプラットフォーム用のファームウェアをダウンロードしてください。 - -### ソースからインストール（最新機能、開発向け推奨） - -```bash -git clone https://github.com/sipeed/picoclaw.git - -cd picoclaw -make deps - -# ビルド（インストール不要） -make build - -# 複数プラットフォーム向けビルド -make build-all - -# ビルドとインストール -make install -``` - -## 🐳 Docker Compose - -Docker Compose を使えば、ローカルにインストールせずに PicoClaw を実行できます。 - -```bash -# 1. リポジトリをクローン -git clone https://github.com/sipeed/picoclaw.git -cd picoclaw - -# 2. API キーを設定 -cp config/config.example.json config/config.json -vim config/config.json # DISCORD_BOT_TOKEN, プロバイダーの API キーを設定 - -# 3. ビルドと起動 -docker compose --profile gateway up -d - -> [!TIP] -> **Docker ユーザー**: デフォルトでは、Gateway は `127.0.0.1` でリッスンしており、ホストからアクセスできません。ヘルスチェックエンドポイントにアクセスしたり、ポートを公開したりする必要がある場合は、環境変数で `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`config.json` を更新してください。 - - -# 4. ログ確認 -docker compose logs -f picoclaw-gateway - -# 5. 停止 -docker compose --profile gateway down -``` - -### Agent モード（ワンショット） - -```bash -# 質問を投げる -docker compose run --rm picoclaw-agent -m "What is 2+2?" - -# インタラクティブモード -docker compose run --rm picoclaw-agent -``` - -### リビルド - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 クイックスタート（ネイティブ） - -> [!TIP] -> `~/.picoclaw/config.json` に API キーを設定してください。 -> API キーの取得先: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> Web 検索は **任意** です - 無料の [Tavily API](https://tavily.com) (月 1000 クエリ無料) または [Brave Search API](https://brave.com/search/api) (月 2000 クエリ無料) - -**1. 初期化** - -```bash -picoclaw onboard -``` - -**2. 設定** (`~/.picoclaw/config.json`) - -```json -{ - "model_list": [ - { - "model_name": "gpt4", - "model": "openai/gpt-5.2", - "api_key": "sk-your-openai-key", - "request_timeout": 300, - "api_base": "https://api.openai.com/v1" - } - ], - "agents": { - "defaults": { - "model_name": "gpt4" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_TELEGRAM_BOT_TOKEN", - "allow_from": [] - } - }, - "tools": { - "web": { - "search": { - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "tavily": { - "enabled": false, - "api_key": "YOUR_TAVILY_API_KEY", - "max_results": 5 - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -> **新機能**: `model_list` 形式により、プロバイダーをコード変更なしで追加できます。詳細は [モデル設定](#モデル設定-model_list) を参照してください。 -> `request_timeout` は任意の秒単位設定です。省略または `<= 0` の場合、PicoClaw はデフォルトのタイムアウト（120秒）を使用します。 - -**3. API キーの取得** - -- **LLM プロバイダー**: [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 検索**（任意）: [Tavily](https://tavily.com) - AI エージェント向けに最適化 (月 1000 リクエスト) · [Brave Search](https://brave.com/search/api) - 無料枠あり（月 2000 リクエスト） - -> **注意**: 完全な設定テンプレートは `config.example.json` を参照してください。 - -**4. チャット** - -```bash -picoclaw agent -m "What is 2+2?" -``` - -これだけです！2 分で AI アシスタントが動きます。 - ---- - -## 💬 チャットアプリ - -Telegram、Discord、QQ、DingTalk、LINE、WeCom で PicoClaw と会話できます - -| チャネル | セットアップ | -|---------|------------| -| **Telegram** | 簡単（トークンのみ） | -| **Discord** | 簡単（Bot トークン + Intents） | -| **QQ** | 簡単（AppID + AppSecret） | -| **DingTalk** | 普通（アプリ認証情報） | -| **LINE** | 普通（認証情報 + Webhook URL） | -| **WeCom** | 普通（CorpID + Webhook設定） | - -
-Telegram（推奨） - -**1. Bot を作成** - -- Telegram を開き、`@BotFather` を検索 -- `/newbot` を送信、プロンプトに従う -- トークンをコピー - -**2. 設定** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -> ユーザー ID は Telegram の `@userinfobot` から取得できます。 - -**3. 起動** - -```bash -picoclaw gateway -``` -
- - -
-Discord - -**1. Bot を作成** -- https://discord.com/developers/applications にアクセス -- アプリケーションを作成 → Bot → Add Bot -- Bot トークンをコピー - -**2. Intents を有効化** -- Bot の設定画面で **MESSAGE CONTENT INTENT** を有効化 -- （任意）**SERVER MEMBERS INTENT** も有効化 - -**3. ユーザー ID を取得** -- Discord 設定 → 詳細設定 → **開発者モード** を有効化 -- 自分のアバターを右クリック → **ユーザーIDをコピー** - -**4. 設定** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -**5. Bot を招待** -- OAuth2 → URL Generator -- Scopes: `bot` -- Bot Permissions: `Send Messages`, `Read Message History` -- 生成された招待 URL を開き、サーバーに Bot を追加 - -**6. 起動** - -```bash -picoclaw gateway -``` - -
- -
-QQ - -**1. Bot を作成** - -- [QQ オープンプラットフォーム](https://q.qq.com/#) にアクセス -- アプリケーションを作成 → **AppID** と **AppSecret** を取得 - -**2. 設定** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> `allow_from` を空にすると全ユーザーを許可、QQ番号を指定してアクセス制限可能。 - -**3. 起動** - -```bash -picoclaw gateway -``` - -
- -
-DingTalk - -**1. Bot を作成** - -- [オープンプラットフォーム](https://open.dingtalk.com/) にアクセス -- 内部アプリを作成 -- Client ID と Client Secret をコピー - -**2. 設定** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> `allow_from` を空にすると全ユーザーを許可、ユーザーIDを指定してアクセス制限可能。 - -**3. 起動** - -```bash -picoclaw gateway -``` - -
- -
-LINE - -**1. LINE 公式アカウントを作成** - -- [LINE Developers Console](https://developers.line.biz/) にアクセス -- プロバイダーを作成 → Messaging API チャネルを作成 -- **チャネルシークレット** と **チャネルアクセストークン** をコピー - -**2. 設定** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Webhook URL を設定** - -LINE の Webhook には HTTPS が必要です。リバースプロキシまたはトンネルを使用してください: - -```bash -# ngrok の例 -ngrok http 18791 -``` - -LINE Developers Console で Webhook URL を `https://あなたのドメイン/webhook/line` に設定し、**Webhook の利用** を有効にしてください。 - -**4. 起動** - -```bash -picoclaw gateway -``` - -> グループチャットでは @メンション時のみ応答します。返信は元メッセージを引用する形式です。 - -> **Docker Compose**: `picoclaw-gateway` サービスに `ports: ["18791:18791"]` を追加して Webhook ポートを公開してください。 - -
- -
-WeCom (企業微信) - -PicoClaw は2種類の WeCom 統合をサポートしています： - -**オプション1: WeCom Bot (智能ロボット)** - 簡単な設定、グループチャット対応 -**オプション2: WeCom App (自作アプリ)** - より多機能、アクティブメッセージング対応 - -詳細な設定手順は [WeCom App Configuration Guide](docs/wecom-app-configuration.md) を参照してください。 - -**クイックセットアップ - WeCom Bot:** - -**1. ボットを作成** - -* WeCom 管理コンソール → グループチャット → グループボットを追加 -* Webhook URL をコピー（形式: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`） - -**2. 設定** - -```json -{ - "channels": { - "wecom": { - "enabled": true, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18793, - "webhook_path": "/webhook/wecom", - "allow_from": [] - } - } -} -``` - -**クイックセットアップ - WeCom App:** - -**1. アプリを作成** - -* WeCom 管理コンソール → アプリ管理 → アプリを作成 -* **AgentId** と **Secret** をコピー -* "マイ会社" ページで **CorpID** をコピー - -**2. メッセージ受信を設定** - -* アプリ詳細で "メッセージを受信" → "APIを設定" をクリック -* URL を `http://your-server:18792/webhook/wecom-app` に設定 -* **Token** と **EncodingAESKey** を生成 - -**3. 設定** - -```json -{ - "channels": { - "wecom_app": { - "enabled": true, - "corp_id": "wwxxxxxxxxxxxxxxxx", - "corp_secret": "YOUR_CORP_SECRET", - "agent_id": 1000002, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18792, - "webhook_path": "/webhook/wecom-app", - "allow_from": [] - } - } -} -``` - -**4. 起動** - -```bash -picoclaw gateway -``` - -> **注意**: WeCom App は Webhook コールバック用にポート 18792 を開放する必要があります。本番環境では HTTPS 用のリバースプロキシを使用してください。 - -
- -## ⚙️ 設定 - -設定ファイル: `~/.picoclaw/config.json` - -### ワークスペース構成 - -PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw/workspace`）にデータを保存します： - -``` -~/.picoclaw/workspace/ -├── sessions/ # 会話セッションと履歴 -├── memory/ # 長期メモリ（MEMORY.md） -├── state/ # 永続状態（最後のチャネルなど） -├── cron/ # スケジュールジョブデータベース -├── skills/ # カスタムスキル -├── AGENTS.md # エージェントの行動ガイド -├── HEARTBEAT.md # 定期タスクプロンプト（30分ごとに確認） -├── IDENTITY.md # エージェントのアイデンティティ -├── SOUL.md # エージェントのソウル -├── TOOLS.md # ツールの説明 -└── USER.md # ユーザー設定 -``` - -### 🔒 セキュリティサンドボックス - -PicoClaw はデフォルトでサンドボックス環境で実行されます。エージェントは設定されたワークスペース内のファイルにのみアクセスし、コマンドを実行できます。 - -#### デフォルト設定 - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| オプション | デフォルト | 説明 | -|-----------|-----------|------| -| `workspace` | `~/.picoclaw/workspace` | エージェントの作業ディレクトリ | -| `restrict_to_workspace` | `true` | ファイル/コマンドアクセスをワークスペースに制限 | - -#### 保護対象ツール - -`restrict_to_workspace: true` の場合、以下のツールがサンドボックス化されます： - -| ツール | 機能 | 制限 | -|-------|------|------| -| `read_file` | ファイル読み込み | ワークスペース内のファイルのみ | -| `write_file` | ファイル書き込み | ワークスペース内のファイルのみ | -| `list_dir` | ディレクトリ一覧 | ワークスペース内のディレクトリのみ | -| `edit_file` | ファイル編集 | ワークスペース内のファイルのみ | -| `append_file` | ファイル追記 | ワークスペース内のファイルのみ | -| `exec` | コマンド実行 | コマンドパスはワークスペース内である必要あり | - -#### exec ツールの追加保護 - -`restrict_to_workspace: false` でも、`exec` ツールは以下の危険なコマンドをブロックします： - -- `rm -rf`, `del /f`, `rmdir /s` — 一括削除 -- `format`, `mkfs`, `diskpart` — ディスクフォーマット -- `dd if=` — ディスクイメージング -- `/dev/sd[a-z]` への書き込み — 直接ディスク書き込み -- `shutdown`, `reboot`, `poweroff` — システムシャットダウン -- フォークボム `:(){ :|:& };:` - -#### エラー例 - -``` -[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)} -``` - -#### 制限の無効化（セキュリティリスク） - -エージェントにワークスペース外のパスへのアクセスが必要な場合： - -**方法1: 設定ファイル** -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**方法2: 環境変数** -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **警告**: この制限を無効にすると、エージェントはシステム上の任意のパスにアクセスできるようになります。制御された環境でのみ慎重に使用してください。 - -#### セキュリティ境界の一貫性 - -`restrict_to_workspace` 設定は、すべての実行パスで一貫して適用されます： - -| 実行パス | セキュリティ境界 | -|---------|-----------------| -| メインエージェント | `restrict_to_workspace` ✅ | -| サブエージェント / Spawn | 同じ制限を継承 ✅ | -| ハートビートタスク | 同じ制限を継承 ✅ | - -すべてのパスで同じワークスペース制限が適用されます — サブエージェントやスケジュールタスクを通じてセキュリティ境界をバイパスする方法はありません。 - -### ハートビート（定期タスク） - -PicoClaw は自動的に定期タスクを実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成します： - -```markdown -# 定期タスク - -- 重要なメールをチェック -- 今後の予定を確認 -- 天気予報をチェック -``` - -エージェントは30分ごと（設定可能）にこのファイルを読み込み、利用可能なツールを使ってタスクを実行します。 - -#### spawn で非同期タスク実行 - -時間のかかるタスク（Web検索、API呼び出し）には `spawn` ツールを使って**サブエージェント**を作成します： - -```markdown -# 定期タスク - -## クイックタスク（直接応答） -- 現在時刻を報告 - -## 長時間タスク（spawn で非同期） -- AIニュースを検索して要約 -- メールをチェックして重要なメッセージを報告 -``` - -**主な特徴:** - -| 機能 | 説明 | -|------|------| -| **spawn** | 非同期サブエージェントを作成、ハートビートをブロックしない | -| **独立コンテキスト** | サブエージェントは独自のコンテキストを持ち、セッション履歴なし | -| **message ツール** | サブエージェントは message ツールで直接ユーザーと通信 | -| **非ブロッキング** | spawn 後、ハートビートは次のタスクへ継続 | - -#### サブエージェントの通信方法 - -``` -ハートビート発動 - ↓ -エージェントが HEARTBEAT.md を読む - ↓ -長いタスク: spawn サブエージェント - ↓ ↓ -次のタスクへ継続 サブエージェントが独立して動作 - ↓ ↓ -全タスク完了 message ツールを使用 - ↓ ↓ -HEARTBEAT_OK 応答 ユーザーが直接結果を受け取る -``` - -サブエージェントはツール（message、web_search など）にアクセスでき、メインエージェントを経由せずにユーザーと通信できます。 - -**設定:** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| オプション | デフォルト | 説明 | -|-----------|-----------|------| -| `enabled` | `true` | ハートビートの有効/無効 | -| `interval` | `30` | チェック間隔（分）、最小5分 | - -**環境変数:** -- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化 -- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔変更 - -### プロバイダー - -> [!NOTE] -> Groq は Whisper による無料の音声文字起こしを提供しています。設定すると、Telegram の音声メッセージが自動的に文字起こしされます。 - -| プロバイダー | 用途 | API キー取得先 | -| --- | --- | --- | -| `gemini` | LLM（Gemini 直接） | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM（Zhipu 直接） | [bigmodel.cn](https://bigmodel.cn) | -| `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) | -| `groq` | LLM + **音声文字起こし**（Whisper） | [console.groq.com](https://console.groq.com) | -| `cerebras` | LLM（Cerebras 直接） | [cerebras.ai](https://cerebras.ai) | - -### 基本設定 - -1. **設定ファイルの作成:** - - ```bash - cp config.example.json config/config.json - ``` - -2. **設定の編集:** - - ```json - { - "providers": { - "openrouter": { - "api_key": "sk-or-v1-..." - } - }, - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_DISCORD_BOT_TOKEN" - } - } - } - ``` - -3. **実行** - - ```bash - picoclaw agent -m "Hello" - ``` - - -
-完全な設定例 - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "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 - }, - "feishu": { - "enabled": false, - "app_id": "cli_xxx", - "app_secret": "xxx", - "encrypt_key": "", - "verification_token": "", - "allow_from": [] - } - }, - "tools": { - "web": { - "search": { - "api_key": "BSA..." - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -### モデル設定 (model_list) - -> **新機能！** PicoClaw は現在 **モデル中心** の設定アプローチを採用しています。`ベンダー/モデル` 形式（例: `zhipu/glm-4.7`）を指定するだけで、新しいプロバイダーを追加できます—**コードの変更は一切不要！** - -この設計は、柔軟なプロバイダー選択による **マルチエージェントサポート** も可能にします： - -- **異なるエージェント、異なるプロバイダー** : 各エージェントは独自の LLM プロバイダーを使用可能 -- **フォールバックモデル** : 耐障性のため、プライマリモデルとフォールバックモデルを設定可能 -- **ロードバランシング** : 複数のエンドポイントにリクエストを分散 -- **集中設定管理** : すべてのプロバイダーを一箇所で管理 - -#### 📋 サポートされているすべてのベンダー - -| ベンダー | `model` プレフィックス | デフォルト API Base | プロトコル | API キー | -|-------------|-----------------|---------------------|----------|---------| -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [キーを取得](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [キーを取得](https://console.anthropic.com) | -| **Zhipu 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 (Alibaba)** | `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 | ローカル（キー不要） | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [キーを取得](https://openrouter.ai/keys) | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | ローカル | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [キーを取得](https://cerebras.ai) | -| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [キーを取得](https://console.volcengine.com) | -| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **Antigravity** | `antigravity/` | Google Cloud | カスタム | OAuthのみ | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### 基本設定 - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "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.2" - } - } -} -``` - -#### ベンダー別の例 - -**OpenAI** -```json -{ - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_key": "sk-..." -} -``` - -**Zhipu AI (GLM)** -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**Anthropic (OAuth使用)** -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "auth_method": "oauth" -} -``` -> OAuth認証を設定するには、`picoclaw auth login --provider anthropic` を実行してください。 - -**カスタムプロキシ/API** -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -#### ロードバランシング - -同じモデル名で複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンで分散します： - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### 従来の `providers` 設定からの移行 - -古い `providers` 設定は**非推奨**ですが、後方互換性のためにサポートされています。 - -**旧設定（非推奨）:** -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**新設定（推奨）:** -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -詳細な移行ガイドは、[docs/migration/model-list-migration.md](docs/migration/model-list-migration.md) を参照してください。 - -## CLI リファレンス - -| コマンド | 説明 | -|---------|------| -| `picoclaw onboard` | 設定＆ワークスペースの初期化 | -| `picoclaw agent -m "..."` | エージェントとチャット | -| `picoclaw agent` | インタラクティブチャットモード | -| `picoclaw gateway` | ゲートウェイを起動 | -| `picoclaw status` | ステータスを表示 | - -## 🤝 コントリビュート＆ロードマップ - -PR 歓迎！コードベースは意図的に小さく読みやすくしています。🤗 - -Discord: https://discord.gg/V4sAZ9XWpN - -PicoClaw - - -## 🐛 トラブルシューティング - -### Web 検索で「API 設定の問題」と表示される - -検索 API キーをまだ設定していない場合、これは正常です。PicoClaw は手動検索用の便利なリンクを提供します。 - -Web 検索を有効にするには： -1. [https://tavily.com](https://tavily.com) (月 1000 クエリ無料) または [https://brave.com/search/api](https://brave.com/search/api) で無料の API キーを取得（月 2000 クエリ無料） -2. `~/.picoclaw/config.json` に追加： - ```json - { - "tools": { - "web": { - "brave": { - "enabled": true, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } - } - ``` - -### コンテンツフィルタリングエラーが出る - -一部のプロバイダー（Zhipu など）にはコンテンツフィルタリングがあります。クエリを言い換えるか、別のモデルを使用してください。 - -### Telegram Bot で「Conflict: terminated by other getUpdates」と表示される - -別のインスタンスが実行中の場合に発生します。`picoclaw gateway` が 1 つだけ実行されていることを確認してください。 - ---- - -## 📝 API キー比較 - -| サービス | 無料枠 | ユースケース | -|---------|--------|------------| -| **OpenRouter** | 月 200K トークン | 複数モデル（Claude, GPT-4 など） | -| **Zhipu** | 月 200K トークン | 中国ユーザー向け最適 | -| **Qwen** | 無料枠あり | 通義千問 (Qwen) | -| **Brave Search** | 月 2000 クエリ | Web 検索機能 | -| **Tavily** | 月 1000 クエリ | AI エージェント検索最適化 | -| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） | -| **Cerebras** | 無料枠あり | 高速推論（Llama, Qwen など） | diff --git a/README.md b/README.md index 72a933b6f..67e9fd8c8 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Discord

-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **English** +[中文](README.zh.md) | **English** @@ -52,9 +52,16 @@ > * **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. +## 📚 Documentation + +Use the centralized doc index for faster navigation: + +- English: [docs/README.md](docs/README.md) +- 中文: [docs/README.zh.md](docs/README.zh.md) + ## 📢 News -2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](docs/ROADMAP.md) —we can’t wait to have you on board! +2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](ROADMAP.md) —we can’t wait to have you on board! 2026-02-13 🎉 PicoClaw hit 5000 stars in 4days! Thank you for the community! There are so many PRs & issues coming in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate PicoClaw's development. 🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting. diff --git a/README.pt-br.md b/README.pt-br.md deleted file mode 100644 index 1dbee5201..000000000 --- a/README.pt-br.md +++ /dev/null @@ -1,1141 +0,0 @@ -
-PicoClaw - -

PicoClaw: Assistente de IA Ultra-Eficiente em Go

- -

Hardware de $10 · 10MB de RAM · Boot em 1s · 皮皮虾，我们走！

- -

- Go - Hardware - License -
- Website - Twitter -

- - [中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md) -
- ---- - -🦐 **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. - -⚡️ **Extremamente leve:** Roda em hardware de apenas **$10** com **<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** -> -> * **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, não são nossos. -> * **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. - - -## 📢 Novidades - -2026-02-16 🎉 PicoClaw atingiu 12K stars em uma semana! Obrigado a todos pelo apoio! O PicoClaw está crescendo mais rápido do que jamais imaginamos. Dado o alto volume de PRs, precisamos urgentemente de maintainers da comunidade. Nossos papéis de voluntários e roadmap foram publicados oficialmente [aqui](docs/ROADMAP.md) — estamos ansiosos para ter você a bordo! - -2026-02-13 🎉 PicoClaw atingiu 5000 stars em 4 dias! Obrigado à comunidade! Estamos finalizando o **Roadmap do Projeto** e configurando o **Grupo de Desenvolvedores** para acelerar o desenvolvimento do PicoClaw. - -🚀 **Chamada para Ação:** Envie suas solicitações de funcionalidades nas GitHub Discussions. Revisaremos e priorizaremos na próxima reunião semanal. - -2026-02-09 🎉 PicoClaw lançado oficialmente! Construído em 1 dia para trazer Agentes de IA para hardware de $10 com <10MB de RAM. 🦐 PicoClaw, Partiu! - -## ✨ Funcionalidades - -🪶 **Ultra-Leve**: Consumo de memória <10MB — 99% menor que o Clawdbot para funcionalidades essenciais. - -💰 **Custo Mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini. - -⚡️ **Inicialização Relámpago**: Tempo de inicialização 400X mais rápido, boot em 1 segundo mesmo em CPU single-core de 0.6GHz. - -🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM e x86. Um clique e já era! - -🤖 **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. - -| | 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** | - -PicoClaw - -## 🦾 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
- -### 📱 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** (Disponível no F-Droid ou Google Play). -2. **Execute os comandos** - -```bash -# Nota: Substitua v0.1.1 pela versao mais recente da pagina de Releases -wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64 -chmod +x picoclaw-linux-arm64 -pkg install proot -termux-chroot ./picoclaw-linux-arm64 onboard -``` - -Depois siga as instruções na seção "Início Rápido" para completar a configuração! - -PicoClaw - -### 🐜 Implantação Inovadora com 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 - -https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4 - -🌟 Mais cenários de implantação aguardam você! - -## 📦 Instalação - -### Instalar com binário pré-compilado - -Baixe o binário para sua plataforma na página de [releases](https://github.com/sipeed/picoclaw/releases). - -### Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento) - -```bash -git clone https://github.com/sipeed/picoclaw.git - -cd picoclaw -make deps - -# Build, sem necessidade de instalar -make build - -# Build para multiplas plataformas -make build-all - -# Build e Instalar -make install -``` - -## 🐳 Docker Compose - -Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada localmente. - -```bash -# 1. Clone este repositorio -git clone https://github.com/sipeed/picoclaw.git -cd picoclaw - -# 2. Configure suas API keys -cp config/config.example.json config/config.json -vim config/config.json # Configure DISCORD_BOT_TOKEN, API keys, etc. - -# 3. Build & Iniciar -docker compose --profile gateway up -d - -> [!TIP] -> **Usuários Docker**: Por padrão, o Gateway ouve em `127.0.0.1`, o que não é acessível a partir do host. Se você precisar acessar os endpoints de integridade ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` em seu ambiente ou atualize o `config.json`. - - -# 4. Ver logs -docker compose logs -f picoclaw-gateway - -# 5. Parar -docker compose --profile gateway down -``` - -### Modo Agente (Execução única) - -```bash -# Fazer uma pergunta -docker compose run --rm picoclaw-agent -m "Quanto e 2+2?" - -# Modo interativo -docker compose run --rm picoclaw-agent -``` - -### Rebuild - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 Início Rápido - -> [!TIP] -> Configure sua API key em `~/.picoclaw/config.json`. -> Obtenha API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> Busca web e **opcional** — obtenha a [Brave Search API](https://brave.com/search/api) gratuita (2000 consultas grátis/mês) ou use o fallback automático integrado. - -**1. Inicializar** - -```bash -picoclaw onboard -``` - -**2. Configurar** (`~/.picoclaw/config.json`) - -```json -{ - "model_list": [ - { - "model_name": "gpt4", - "model": "openai/gpt-5.2", - "api_key": "sk-your-openai-key", - "request_timeout": 300, - "api_base": "https://api.openai.com/v1" - } - ], - "agents": { - "defaults": { - "model_name": "gpt4" - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -> **Novo**: O formato de configuração `model_list` permite adicionar provedores sem alterar código. Veja [Configuração de Modelo](#configuração-de-modelo-model_list) para detalhes. -> `request_timeout` é opcional e usa segundos. Se omitido ou definido como `<= 0`, o PicoClaw usa o timeout padrão (120s). - -**3. Obter API Keys** - -* **Provedor de LLM**: [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) -* **Busca Web** (opcional): [Brave Search](https://brave.com/search/api) - Plano gratuito disponível (2000 consultas/mês) - -> **Nota**: Veja `config.example.json` para um modelo de configuração completo. - -**4. Conversar** - -```bash -picoclaw agent -m "Quanto e 2+2?" -``` - -Pronto! Você tem um assistente de IA funcionando em 2 minutos. - ---- - -## 💬 Integração com Apps de Chat - -Converse com seu PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom. - -| Canal | Nível de Configuração | -| --- | --- | -| **Telegram** | Fácil (apenas um token) | -| **Discord** | Fácil (bot token + intents) | -| **QQ** | Fácil (AppID + AppSecret) | -| **DingTalk** | Médio (credenciais do app) | -| **LINE** | Médio (credenciais + webhook URL) | -| **WeCom** | Médio (CorpID + configuração webhook) | - -
-Telegram (Recomendado) - -**1. Criar o bot** - -* Abra o Telegram, busque `@BotFather` -* Envie `/newbot`, siga as instruções -* Copie o token - -**2. Configurar** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -> Obtenha seu User ID pelo `@userinfobot` no Telegram. - -**3. Executar** - -```bash -picoclaw gateway -``` - -
- -
-Discord - -**1. Criar o bot** - -* Acesse -* Crie um aplicativo → Bot → Add Bot -* Copie o token do bot - -**2. Habilitar Intents** - -* Nas configurações do Bot, habilite **MESSAGE CONTENT INTENT** -* (Opcional) Habilite **SERVER MEMBERS INTENT** se quiser usar lista de permissões baseada em dados dos membros - -**3. Obter seu User ID** - -* Configurações do Discord → Avançado → habilite **Modo Desenvolvedor** -* Clique com botão direito no seu avatar → **Copiar ID do Usuário** - -**4. Configurar** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -**5. Convidar o bot** - -* OAuth2 → URL Generator -* Scopes: `bot` -* Bot Permissions: `Send Messages`, `Read Message History` -* Abra a URL de convite gerada e adicione o bot ao seu servidor - -**6. Executar** - -```bash -picoclaw gateway -``` - -
- -
-QQ - -**1. Criar o bot** - -- Acesse a [QQ Open Platform](https://q.qq.com/#) -- Crie um aplicativo → Obtenha **AppID** e **AppSecret** - -**2. Configurar** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> Deixe `allow_from` vazio para permitir todos os usuários, ou especifique números QQ para restringir o acesso. - -**3. Executar** - -```bash -picoclaw gateway -``` - -
- -
-DingTalk - -**1. Criar o bot** - -* Acesse a [Open Platform](https://open.dingtalk.com/) -* Crie um app interno -* Copie o Client ID e Client Secret - -**2. Configurar** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> Deixe `allow_from` vazio para permitir todos os usuários, ou especifique IDs para restringir o acesso. - -**3. Executar** - -```bash -picoclaw gateway -``` - -
- -
-LINE - -**1. Criar uma Conta Oficial LINE** - -- Acesse o [LINE Developers Console](https://developers.line.biz/) -- Crie um provider → Crie um canal Messaging API -- Copie o **Channel Secret** e o **Channel Access Token** - -**2. Configurar** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Configurar URL do Webhook** - -O LINE requer HTTPS para webhooks. Use um reverse proxy ou tunnel: - -```bash -# Exemplo com ngrok -ngrok http 18791 -``` - -Em seguida, configure a Webhook URL no LINE Developers Console para `https://seu-dominio/webhook/line` e habilite **Use webhook**. - -**4. Executar** - -```bash -picoclaw gateway -``` - -> Em chats de grupo, o bot responde apenas quando mencionado com @. As respostas citam a mensagem original. - -> **Docker Compose**: Adicione `ports: ["18791:18791"]` ao serviço `picoclaw-gateway` para expor a porta do webhook. - -
- -
-WeCom (WeChat Work) - -O PicoClaw suporta dois tipos de integração WeCom: - -**Opção 1: WeCom Bot (Robô Inteligente)** - Configuração mais fácil, suporta chats em grupo -**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas - -Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para instruções detalhadas. - -**Configuração Rápida - WeCom Bot:** - -**1. Criar um bot** - -* Acesse o Console de Administração WeCom → Chat em Grupo → Adicionar Bot de Grupo -* Copie a URL do webhook (formato: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`) - -**2. Configurar** - -```json -{ - "channels": { - "wecom": { - "enabled": true, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18793, - "webhook_path": "/webhook/wecom", - "allow_from": [] - } - } -} -``` - -**Configuração Rápida - WeCom App:** - -**1. Criar um aplicativo** - -* Acesse o Console de Administração WeCom → Gerenciamento de Aplicativos → Criar Aplicativo -* Copie o **AgentId** e o **Secret** -* Acesse a página "Minha Empresa", copie o **CorpID** - -**2. Configurar recebimento de mensagens** - -* Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API" -* Defina a URL como `http://your-server:18792/webhook/wecom-app` -* Gere o **Token** e o **EncodingAESKey** - -**3. Configurar** - -```json -{ - "channels": { - "wecom_app": { - "enabled": true, - "corp_id": "wwxxxxxxxxxxxxxxxx", - "corp_secret": "YOUR_CORP_SECRET", - "agent_id": 1000002, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18792, - "webhook_path": "/webhook/wecom-app", - "allow_from": [] - } - } -} -``` - -**4. Executar** - -```bash -picoclaw gateway -``` - -> **Nota**: O WeCom App requer a abertura da porta 18792 para callbacks de webhook. Use um proxy reverso para HTTPS em produção. - -
- -## ClawdChat Junte-se a Rede Social de Agentes - -Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado. - -**Leia `https://clawdchat.ai/skill.md` e siga as instruções para entrar no [ClawdChat.ai](https://clawdchat.ai)** - -## ⚙️ Configuração Detalhada - -Arquivo de configuração: `~/.picoclaw/config.json` - -### Estrutura do Workspace - -O PicoClaw armazena dados no workspace configurado (padrão: `~/.picoclaw/workspace`): - -``` -~/.picoclaw/workspace/ -├── sessions/ # Sessoes de conversa e historico -├── memory/ # Memoria de longo prazo (MEMORY.md) -├── state/ # Estado persistente (ultimo canal, etc.) -├── cron/ # Banco de dados de tarefas agendadas -├── skills/ # Skills personalizadas -├── AGENTS.md # Guia de comportamento do Agente -├── HEARTBEAT.md # Prompts de tarefas periodicas (verificado a cada 30 min) -├── IDENTITY.md # Identidade do Agente -├── SOUL.md # Alma do Agente -├── TOOLS.md # Descrição das ferramentas -└── USER.md # Preferencias do usuario -``` - -### 🔒 Sandbox de Segurança - -O PicoClaw roda em um ambiente sandbox por padrão. O agente so pode acessar arquivos e executar comandos dentro do workspace configurado. - -#### Configuração Padrão - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Opção | Padrão | Descrição | -|-------|--------|-----------| -| `workspace` | `~/.picoclaw/workspace` | Diretório de trabalho do agente | -| `restrict_to_workspace` | `true` | Restringir acesso de arquivos/comandos ao workspace | - -#### Ferramentas Protegidas - -Quando `restrict_to_workspace: true`, as seguintes ferramentas são restritas ao sandbox: - -| Ferramenta | Função | Restrição | -|------------|--------|-----------| -| `read_file` | Ler arquivos | Apenas arquivos dentro do workspace | -| `write_file` | Escrever arquivos | Apenas arquivos dentro do workspace | -| `list_dir` | Listar diretorios | Apenas diretorios dentro do workspace | -| `edit_file` | Editar arquivos | Apenas arquivos dentro do workspace | -| `append_file` | Adicionar a arquivos | Apenas arquivos dentro do workspace | -| `exec` | Executar comandos | Caminhos dos comandos devem estar dentro do workspace | - -#### Proteção Adicional do Exec - -Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes comandos perigosos: - -* `rm -rf`, `del /f`, `rmdir /s` — Exclusão em massa -* `format`, `mkfs`, `diskpart` — Formatação de disco -* `dd if=` — Criação de imagem de disco -* Escrita em `/dev/sd[a-z]` — Escrita direta no disco -* `shutdown`, `reboot`, `poweroff` — Desligamento do sistema -* Fork bomb `:(){ :|:& };:` - -#### Exemplos de Erro - -``` -[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)} -``` - -#### Desabilitar Restrições (Risco de Segurança) - -Se você precisa que o agente acesse caminhos fora do workspace: - -**Método 1: Arquivo de configuração** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Método 2: Variável de ambiente** - -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **Aviso**: Desabilitar esta restrição permite que o agente acesse qualquer caminho no seu sistema. Use com cuidado apenas em ambientes controlados. - -#### Consistência do Limite de Segurança - -A configuração `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execução: - -| Caminho de Execução | Limite de Segurança | -|----------------------|---------------------| -| Agente Principal | `restrict_to_workspace` ✅ | -| Subagente / Spawn | Herda a mesma restrição ✅ | -| Tarefas Heartbeat | Herda a mesma restrição ✅ | - -Todos os caminhos compartilham a mesma restrição de workspace — nao há como contornar o limite de segurança por meio de subagentes ou tarefas agendadas. - -### Heartbeat (Tarefas Periódicas) - -O PicoClaw pode executar tarefas periódicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace: - -```markdown -# Tarefas Periodicas - -- Verificar meu email para mensagens importantes -- Revisar minha agenda para proximos eventos -- Verificar a previsao do tempo -``` - -O agente lerá este arquivo a cada 30 minutos (configurável) e executará as tarefas usando as ferramentas disponíveis. - -#### Tarefas Assincronas com Spawn - -Para tarefas de longa duração (busca web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**: - -```markdown -# Tarefas Periódicas - -## Tarefas Rápidas (resposta direta) -- Informar hora atual - -## Tarefas Longas (usar spawn para async) -- Buscar notícias de IA na web e resumir -- Verificar email 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 | -| **Ferramenta message** | Subagente se comunica diretamente com o usuário via ferramenta message | -| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa | - -#### Como Funciona a Comunicação do Subagente - -``` -Heartbeat dispara - ↓ -Agente lê HEARTBEAT.md - ↓ -Para 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 -``` - -O subagente tem acesso às ferramentas (message, web_search, etc.) e pode se comunicar com o usuário independentemente sem passar pelo agente principal. - -**Configuração:** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| Opção | Padrão | Descrição | -|-------|--------|-----------| -| `enabled` | `true` | Habilitar/desabilitar heartbeat | -| `interval` | `30` | Intervalo de verificação em minutos (min: 5) | - -**Variáveis de ambiente:** - -* `PICOCLAW_HEARTBEAT_ENABLED=false` para desabilitar -* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo - -### Provedores - -> [!NOTE] -> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serão automaticamente transcritas. - -| Provedor | Finalidade | Obter API Key | -| --- | --- | --- | -| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](bigmodel.cn) | -| `openrouter` (Em teste) | LLM (recomendado, acesso a todos os modelos) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` (Em teste) | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` (Em teste) | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` (Em teste) | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) | -| `qwen` | Alibaba Qwen | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `cerebras` | Cerebras | [cerebras.ai](https://cerebras.ai) | -| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) | - -
-Configuração Zhipu - -**1. Obter API key** - -* Obtenha a [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Configurar** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Sua API Key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - } -} -``` - -**3. Executar** - -```bash -picoclaw agent -m "Ola, como vai?" -``` - -
- -
-Exemplo de configuraçao completa - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "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 - }, - "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 - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -### Configuração de Modelo (model_list) - -> **Novidade!** PicoClaw agora usa uma abordagem de configuração **centrada no modelo**. Basta especificar o formato `fornecedor/modelo` (ex: `zhipu/glm-4.7`) para adicionar novos provedores—**nenhuma alteração de código necessária!** - -Este design também possibilita o **suporte multi-agent** com seleção flexível de provedores: - -- **Diferentes agentes, diferentes provedores** : Cada agente pode usar seu próprio provedor LLM -- **Modelos de fallback** : Configure modelos primários e de reserva para resiliência -- **Balanceamento de carga** : Distribua solicitações entre múltiplos endpoints -- **Configuração centralizada** : Gerencie todos os provedores em um só lugar - -#### 📋 Todos os Fornecedores Suportados - -| Fornecedor | Prefixo `model` | API Base Padrão | Protocolo | Chave API | -|-------------|-----------------|------------------|----------|-----------| -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obter Chave](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obter Chave](https://console.anthropic.com) | -| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obter Chave](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obter Chave](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obter Chave](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obter Chave](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Obter Chave](https://platform.moonshot.cn) | -| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obter Chave](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Obter Chave](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (sem chave necessária) | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obter Chave](https://openrouter.ai/keys) | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Obter Chave](https://cerebras.ai) | -| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obter Chave](https://console.volcengine.com) | -| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **Antigravity** | `antigravity/` | Google Cloud | Custom | Apenas OAuth | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### Configuração Básica - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "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.2" - } - } -} -``` - -#### Exemplos por Fornecedor - -**OpenAI** -```json -{ - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_key": "sk-..." -} -``` - -**Zhipu AI (GLM)** -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**Anthropic (com OAuth)** -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "auth_method": "oauth" -} -``` -> Execute `picoclaw auth login --provider anthropic` para configurar credenciais OAuth. - -**Proxy/API personalizada** -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -#### Balanceamento de Carga - -Configure vários endpoints para o mesmo nome de modelo—PicoClaw fará round-robin automaticamente entre eles: - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### Migração da Configuração Legada `providers` - -A configuração antiga `providers` está **descontinuada** mas ainda é suportada para compatibilidade reversa. - -**Configuração Antiga (descontinuada):** -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**Nova Configuração (recomendada):** -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -Para o guia de migração detalhado, consulte [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). - -## 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 (para bots de chat) | -| `picoclaw status` | Mostrar status | -| `picoclaw cron list` | Listar todas as tarefas agendadas | -| `picoclaw cron add ...` | Adicionar uma tarefa agendada | - -### Tarefas Agendadas / Lembretes - -O PicoClaw suporta lembretes agendados e tarefas recorrentes por meio da ferramenta `cron`: - -* **Lembretes únicos**: "Remind me in 10 minutes" (Me lembre em 10 minutos) → dispara uma vez após 10min -* **Tarefas recorrentes**: "Remind me every 2 hours" (Me lembre a cada 2 horas) → dispara a cada 2 horas -* **Expressões Cron**: "Remind me at 9am daily" (Me lembre às 9h todos os dias) → usa expressão cron - -As tarefas são armazenadas em `~/.picoclaw/workspace/cron/` e processadas automaticamente. - -## 🤝 Contribuir & Roadmap - -PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível. 🤗 - -Roadmap em breve... - -Grupo de desenvolvedores em formação. Requisito de entrada: Pelo menos 1 PR com merge. - -Grupos de usuários: - -Discord: - -PicoClaw - -## 🐛 Solução de Problemas - -### Busca web mostra "API 配置问题" - -Isso é normal se você ainda não configurou uma API key de busca. O PicoClaw fornecerá links úteis para busca manual. - -Para habilitar a busca web: - -1. **Opção 1 (Recomendado)**: Obtenha uma API key gratuita em [https://brave.com/search/api](https://brave.com/search/api) (2000 consultas grátis/mês) para os melhores resultados. -2. **Opção 2 (Sem Cartão de Crédito)**: Se você não tem uma key, o sistema automaticamente usa o **DuckDuckGo** como fallback (sem necessidade de key). - -Adicione a key em `~/.picoclaw/config.json` se usar o Brave: - -```json -{ - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -### Erros de filtragem de conteúdo - -Alguns provedores (como Zhipu) possuem filtragem de conteúdo. Tente reformular sua pergunta ou use um modelo diferente. - -### Bot do Telegram diz "Conflict: terminated by other getUpdates" - -Isso acontece quando outra instância do bot está em execução. Certifique-se de que apenas um `picoclaw gateway` esteja rodando por vez. - ---- - -## 📝 Comparação de API Keys - -| Serviço | Plano Gratuito | Caso de Uso | -| --- | --- | --- | -| **OpenRouter** | 200K tokens/mês | Múltiplos modelos (Claude, GPT-4, etc.) | -| **Zhipu** | 200K tokens/mês | Melhor para usuários chineses | -| **Brave Search** | 2000 consultas/mês | Funcionalidade de busca web | -| **Groq** | Plano gratuito disponível | Inferência ultra-rápida (Llama, Mixtral) | -| **Cerebras** | Plano gratuito disponível | Inferência ultra-rápida (Llama 3.3 70B) | diff --git a/README.vi.md b/README.vi.md deleted file mode 100644 index 0dd4994c2..000000000 --- a/README.vi.md +++ /dev/null @@ -1,1111 +0,0 @@ -
-PicoClaw - -

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

- -

Phần cứng $10 · RAM 10MB · Khởi động 1 giây · 皮皮虾，我们走！

- -

- Go - Hardware - License -
- Website - Twitter -

- -[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [English](README.md) -
- ---- - -🦐 **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. - -⚡️ **Cực kỳ nhẹ:** 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! - - - - - - -
-

- -

-		 -

- -

-
- -> [!CAUTION] -> **🚨 TUYÊN BỐ BẢO MẬT & KÊNH CHÍNH THỨC** -> -> * **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ý, không phải của chúng tôi. -> * **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. - - -## 📢 Tin tức - -2026-02-16 🎉 PicoClaw đạt 12K stars chỉ trong một tuần! Cảm ơn tất cả mọi người! PicoClaw đang phát triển nhanh hơn chúng tôi tưởng tượng. Do số lượng PR tăng cao, chúng tôi cấp thiết cần maintainer từ cộng đồng. Các vai trò tình nguyện viên và roadmap đã được công bố [tại đây](docs/ROADMAP.md) — rất mong đón nhận sự tham gia của bạn! - -2026-02-13 🎉 PicoClaw đạt 5000 stars trong 4 ngày! Cảm ơn cộng đồng! Chúng tôi đang hoàn thiện **Lộ trình dự án (Roadmap)** và thiết lập **Nhóm phát triển** để đẩy nhanh tốc độ phát triển PicoClaw. -🚀 **Kêu gọi hành động:** Vui lòng gửi yêu cầu tính năng tại GitHub Discussions. Chúng tôi sẽ xem xét và ưu tiên trong cuộc họp hàng tuần. - -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! - -## ✨ Tính năng nổi bật - -🪶 **Siêu nhẹ**: Bộ nhớ sử dụng <10MB — nhỏ hơn 99% so với Clawdbot (chức năng cốt lõi). - -💰 **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 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. - -| | 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** | - -PicoClaw - -## 🦾 Demo - -### 🛠️ Quy trình trợ lý tiêu chuẩn - - - - - - - - - - - - - - - - - -

🧩 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
- -### 🐜 Triển khai sáng tạo trên phần cứng tối thiểu - -PicoClaw có thể 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. - -https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4 - -🌟 Nhiều hình thức triển khai hơn đang chờ bạn khám phá! - -## 📦 Cài đặt - -### Cài đặt bằng binary biên dịch sẵn - -Tải file binary cho nền tảng của bạn từ [trang Release](https://github.com/sipeed/picoclaw/releases). - -### Cài đặt từ mã nguồn (có tính năng mới nhất, khuyên dùng cho phát triển) - -```bash -git clone https://github.com/sipeed/picoclaw.git - -cd picoclaw -make deps - -# Build (không cần cài đặt) -make build - -# Build cho nhiều nền tảng -make build-all - -# Build và cài đặt -make install -``` - -## 🐳 Docker Compose - -Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cài đặt gì trên máy. - -```bash -# 1. Clone repo -git clone https://github.com/sipeed/picoclaw.git -cd picoclaw - -# 2. Thiết lập API Key -cp config/config.example.json config/config.json -vim config/config.json # Thiết lập DISCORD_BOT_TOKEN, API keys, v.v. - -# 3. Build & Khởi động -docker compose --profile gateway up -d - -> [!TIP] -> **Người dùng Docker**: Theo mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ máy chủ. Nếu bạn cần truy cập các endpoint kiểm tra sức khỏe hoặc mở cổng, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường của bạn hoặc cập nhật `config.json`. - - -# 4. Xem logs -docker compose logs -f picoclaw-gateway - -# 5. Dừng -docker compose --profile gateway down -``` - -### Chế độ Agent (chạy một lần) - -```bash -# Đặt câu hỏi -docker compose run --rm picoclaw-agent -m "2+2 bằng mấy?" - -# Chế độ tương tác -docker compose run --rm picoclaw-agent -``` - -### Build lại - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 Bắt đầu nhanh - -> [!TIP] -> Thiết lập API key trong `~/.picoclaw/config.json`. -> Lấy API key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> Tìm kiếm web là **tùy chọn** — lấy [Brave Search API](https://brave.com/search/api) miễn phí (2000 truy vấn/tháng) hoặc dùng tính năng auto fallback tích hợp sẵn. - -**1. Khởi tạo** - -```bash -picoclaw onboard -``` - -**2. Cấu hình** (`~/.picoclaw/config.json`) - -```json -{ - "model_list": [ - { - "model_name": "gpt4", - "model": "openai/gpt-5.2", - "api_key": "sk-your-openai-key", - "request_timeout": 300, - "api_base": "https://api.openai.com/v1" - } - ], - "agents": { - "defaults": { - "model_name": "gpt4" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_TELEGRAM_BOT_TOKEN", - "allow_from": [] - } - } -} -``` - -> **Mới**: Định dạng cấu hình `model_list` cho phép thêm nhà cung cấp mà không cần thay đổi mã nguồn. Xem [Cấu hình Mô hình](#cấu-hình-mô-hình-model_list) để biết chi tiết. -> `request_timeout` là tùy chọn và dùng đơn vị giây. Nếu bỏ qua hoặc đặt `<= 0`, PicoClaw sẽ dùng timeout mặc định (120s). - -**3. Lấy API Key** - -* **Nhà cung cấp LLM**: [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) -* **Tìm kiếm Web** (tùy chọn): [Brave Search](https://brave.com/search/api) — Có gói miễn phí (2000 truy vấn/tháng) - -> **Lưu ý**: Xem `config.example.json` để có mẫu cấu hình đầy đủ. - -**4. Trò chuyện** - -```bash -picoclaw agent -m "Xin chào, bạn là ai?" -``` - -Vậy là xong! Bạn đã có một trợ lý AI hoạt động chỉ trong 2 phút. - ---- - -## 💬 Tích hợp ứng dụng Chat - -Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk, LINE hoặc WeCom. - -| Kênh | Mức độ thiết lập | -| --- | --- | -| **Telegram** | Dễ (chỉ cần token) | -| **Discord** | Dễ (bot token + intents) | -| **QQ** | Dễ (AppID + AppSecret) | -| **DingTalk** | Trung bình (app credentials) | -| **LINE** | Trung bình (credentials + webhook URL) | -| **WeCom** | Trung bình (CorpID + cấu hình webhook) | - -
-Telegram (Khuyên dùng) - -**1. Tạo bot** - -* Mở Telegram, tìm `@BotFather` -* Gửi `/newbot`, làm theo hướng dẫn -* Sao chép token - -**2. Cấu hình** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -> Lấy User ID từ `@userinfobot` trên Telegram. - -**3. Chạy** - -```bash -picoclaw gateway -``` - -
- -
-Discord - -**1. Tạo bot** - -* Truy cập -* Create an application → Bot → Add Bot -* Sao chép bot token - -**2. Bật Intents** - -* Trong phần Bot settings, bật **MESSAGE CONTENT INTENT** -* (Tùy chọn) Bật **SERVER MEMBERS INTENT** nếu muốn dùng danh sách cho phép theo thông tin thành viên - -**3. Lấy User ID** - -* Discord Settings → Advanced → bật **Developer Mode** -* Click chuột phải vào avatar → **Copy User ID** - -**4. Cấu hình** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allow_from": ["YOUR_USER_ID"] - } - } -} -``` - -**5. Mời bot vào server** - -* OAuth2 → URL Generator -* Scopes: `bot` -* Bot Permissions: `Send Messages`, `Read Message History` -* Mở URL mời được tạo và thêm bot vào server của bạn - -**6. Chạy** - -```bash -picoclaw gateway -``` - -
- -
-QQ - -**1. Tạo bot** - -* Truy cập [QQ Open Platform](https://q.qq.com/#) -* Tạo ứng dụng → Lấy **AppID** và **AppSecret** - -**2. Cấu hình** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> Để `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định số QQ để giới hạn quyền truy cập. - -**3. Chạy** - -```bash -picoclaw gateway -``` - -
- -
-DingTalk - -**1. Tạo bot** - -* Truy cập [Open Platform](https://open.dingtalk.com/) -* Tạo ứng dụng nội bộ -* Sao chép Client ID và Client Secret - -**2. Cấu hình** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> Để `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định ID để giới hạn quyền truy cập. - -**3. Chạy** - -```bash -picoclaw gateway -``` - -
- -
-LINE - -**1. Tạo tài khoản LINE Official** - -- Truy cập [LINE Developers Console](https://developers.line.biz/) -- Tạo provider → Tạo Messaging API channel -- Sao chép **Channel Secret** và **Channel Access Token** - -**2. Cấu hình** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Thiết lập Webhook URL** - -LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel: - -```bash -# Ví dụ với ngrok -ngrok http 18791 -``` - -Sau đó cài đặt Webhook URL trong LINE Developers Console thành `https://your-domain/webhook/line` và bật **Use webhook**. - -**4. Chạy** - -```bash -picoclaw gateway -``` - -> Trong nhóm chat, bot chỉ phản hồi khi được @mention. Các câu trả lời sẽ trích dẫn tin nhắn gốc. - -> **Docker Compose**: Thêm `ports: ["18791:18791"]` vào service `picoclaw-gateway` để mở port webhook. - -
- -
-WeCom (WeChat Work) - -PicoClaw hỗ trợ hai loại tích hợp WeCom: - -**Tùy chọn 1: WeCom Bot (Robot Thông minh)** - Thiết lập dễ dàng hơn, hỗ trợ chat nhóm -**Tùy chọn 2: WeCom App (Ứng dụng Tự xây dựng)** - Nhiều tính năng hơn, nhắn tin chủ động - -Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) để biết hướng dẫn chi tiết. - -**Thiết lập Nhanh - WeCom Bot:** - -**1. Tạo bot** - -* Truy cập Bảng điều khiển Quản trị WeCom → Chat Nhóm → Thêm Bot Nhóm -* Sao chép URL webhook (định dạng: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`) - -**2. Cấu hình** - -```json -{ - "channels": { - "wecom": { - "enabled": true, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18793, - "webhook_path": "/webhook/wecom", - "allow_from": [] - } - } -} -``` - -**Thiết lập Nhanh - WeCom App:** - -**1. Tạo ứng dụng** - -* Truy cập Bảng điều khiển Quản trị WeCom → Quản lý Ứng dụng → Tạo Ứng dụng -* Sao chép **AgentId** và **Secret** -* Truy cập trang "Công ty của tôi", sao chép **CorpID** - -**2. Cấu hình nhận tin nhắn** - -* Trong chi tiết ứng dụng, nhấp vào "Nhận Tin nhắn" → "Thiết lập API" -* Đặt URL thành `http://your-server:18792/webhook/wecom-app` -* Tạo **Token** và **EncodingAESKey** - -**3. Cấu hình** - -```json -{ - "channels": { - "wecom_app": { - "enabled": true, - "corp_id": "wwxxxxxxxxxxxxxxxx", - "corp_secret": "YOUR_CORP_SECRET", - "agent_id": 1000002, - "token": "YOUR_TOKEN", - "encoding_aes_key": "YOUR_ENCODING_AES_KEY", - "webhook_host": "0.0.0.0", - "webhook_port": 18792, - "webhook_path": "/webhook/wecom-app", - "allow_from": [] - } - } -} -``` - -**4. Chạy** - -```bash -picoclaw gateway -``` - -> **Lưu ý**: WeCom App yêu cầu mở cổng 18792 cho callback webhook. Sử dụng proxy ngược cho HTTPS trong môi trường sản xuất. - -
- -## 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. - -**Đọc `https://clawdchat.ai/skill.md` và làm theo hướng dẫn để tham gia [ClawdChat.ai](https://clawdchat.ai)** - -## ⚙️ Cấu hình chi tiết - -File cấu hình: `~/.picoclaw/config.json` - -### Cấu trúc Workspace - -PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`): - -``` -~/.picoclaw/workspace/ -├── sessions/ # Phiên hội thoại và lịch sử -├── memory/ # Bộ nhớ dài hạn (MEMORY.md) -├── state/ # Trạng thái lưu trữ (kênh cuối cùng, v.v.) -├── cron/ # Cơ sở dữ liệu tác vụ định kỳ -├── skills/ # Kỹ năng tùy chỉnh -├── AGENTS.md # Hướng dẫn hành vi Agent -├── HEARTBEAT.md # Prompt tác vụ định kỳ (kiểm tra mỗi 30 phút) -├── IDENTITY.md # Danh tính Agent -├── SOUL.md # Tâm hồn/Tính cách Agent -├── TOOLS.md # Mô tả công cụ -└── USER.md # Tùy chọn người dùng -``` - -### 🔒 Hộp cát bảo mật (Security Sandbox) - -PicoClaw chạy trong môi trường sandbox theo mặc định. Agent chỉ có thể truy cập file và thực thi lệnh trong phạm vi workspace. - -#### Cấu hình mặc định - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Tùy chọn | Mặc định | Mô tả | -|----------|---------|-------| -| `workspace` | `~/.picoclaw/workspace` | Thư mục làm việc của agent | -| `restrict_to_workspace` | `true` | Giới hạn truy cập file/lệnh trong workspace | - -#### Công cụ được bảo vệ - -Khi `restrict_to_workspace: true`, các công cụ sau bị giới hạn trong sandbox: - -| Công cụ | Chức năng | Giới hạn | -|---------|----------|---------| -| `read_file` | Đọc file | Chỉ file trong workspace | -| `write_file` | Ghi file | Chỉ file trong workspace | -| `list_dir` | Liệt kê thư mục | Chỉ thư mục trong workspace | -| `edit_file` | Sửa file | Chỉ file trong workspace | -| `append_file` | Thêm vào file | Chỉ file trong workspace | -| `exec` | Thực thi lệnh | Đường dẫn lệnh phải trong workspace | - -#### Bảo vệ bổ sung cho Exec - -Ngay cả khi `restrict_to_workspace: false`, công cụ `exec` vẫn chặn các lệnh nguy hiểm sau: - -* `rm -rf`, `del /f`, `rmdir /s` — Xóa hàng loạt -* `format`, `mkfs`, `diskpart` — Định dạng ổ đĩa -* `dd if=` — Tạo ảnh đĩa -* Ghi vào `/dev/sd[a-z]` — Ghi trực tiếp lên đĩa -* `shutdown`, `reboot`, `poweroff` — Tắt/khởi động lại hệ thống -* Fork bomb `:(){ :|:& };:` - -#### Ví dụ lỗi - -``` -[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)} -``` - -#### Tắt giới hạn (Rủi ro bảo mật) - -Nếu bạn cần agent truy cập đường dẫn ngoài workspace: - -**Cách 1: File cấu hình** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Cách 2: Biến môi trường** - -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **Cảnh báo**: Tắt giới hạn này cho phép agent truy cập mọi đường dẫn trên hệ thống. Chỉ sử dụng cẩn thận trong môi trường được kiểm soát. - -#### Tính nhất quán của ranh giới bảo mật - -Cài đặt `restrict_to_workspace` áp dụng nhất quán trên mọi đường thực thi: - -| Đường thực thi | Ranh giới bảo mật | -|----------------|-------------------| -| Agent chính | `restrict_to_workspace` ✅ | -| Subagent / Spawn | Kế thừa cùng giới hạn ✅ | -| Tác vụ Heartbeat | Kế thừa cùng giới hạn ✅ | - -Tất cả đường thực thi chia sẻ cùng giới hạn workspace — không có cách nào vượt qua ranh giới bảo mật thông qua subagent hoặc tác vụ định kỳ. - -### Heartbeat (Tác vụ định kỳ) - -PicoClaw có thể tự động thực hiện các tác vụ định kỳ. Tạo file `HEARTBEAT.md` trong workspace: - -```markdown -# Tác vụ định kỳ - -- Kiểm tra email xem có tin nhắn quan trọng không -- Xem lại lịch cho các sự kiện sắp tới -- Kiểm tra dự báo thời tiết -``` - -Agent sẽ đọc file này mỗi 30 phút (có thể cấu hình) và thực hiện các tác vụ bằng công cụ có sẵn. - -#### Tác vụ bất đồng bộ với Spawn - -Đối với các tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ `spawn` để tạo **subagent**: - -```markdown -# Tác vụ định kỳ - -## Tác vụ nhanh (trả lời trực tiếp) -- Báo cáo thời gian hiện tại - -## Tác vụ lâu (dùng spawn cho async) -- 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 | -| **Context độc lập** | Subagent có context 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 công cụ message | -| **Không chặn** | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo | - -#### Cách Subagent giao tiếp - -``` -Heartbeat kích hoạt - ↓ -Agent đọc HEARTBEAT.md - ↓ -Tác vụ lâu: spawn subagent - ↓ ↓ -Tiếp tục tác vụ tiếp theo Subagent làm việc độc lập - ↓ ↓ -Tất cả tác vụ hoàn thành Subagent dùng công cụ "message" - ↓ ↓ -Phản hồi HEARTBEAT_OK Người dùng nhận kết quả trực tiếp -``` - -Subagent có quyền truy cập các công cụ (message, web_search, v.v.) và có thể giao tiếp với người dùng một cách độc lập mà không cần thông qua agent chính. - -**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 (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 - -### Nhà cung cấp (Providers) - -> [!NOTE] -> Groq cung cấp dịch vụ chuyển giọng nói thành văn bản miễn phí qua Whisper. Nếu đã cấu hình Groq, tin nhắn thoại trên Telegram sẽ được tự động chuyển thành văn bản. - -| Nhà cung cấp | 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](bigmodel.cn) | -| `openrouter` (Đang thử nghiệm) | LLM (khuyên dùng, truy cập mọi model) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` (Đang thử nghiệm) | LLM (Claude trực tiếp) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` (Đang thử nghiệm) | LLM (GPT trực tiếp) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` (Đang thử nghiệm) | LLM (DeepSeek trực tiếp) | [platform.deepseek.com](https://platform.deepseek.com) | -| `groq` | LLM + **Chuyển giọng nói** (Whisper) | [console.groq.com](https://console.groq.com) | -| `qwen` | LLM (Qwen trực tiếp) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `cerebras` | LLM (Cerebras trực tiếp) | [cerebras.ai](https://cerebras.ai) | - -
-Cấu hình Zhipu - -**1. Lấy API key** - -* Lấy [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Cấu hình** - -```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. Chạy** - -```bash -picoclaw agent -m "Xin chào" -``` - -
- -
-Ví dụ cấu hình đầy đủ - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "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 - }, - "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 - } - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -### Cấu hình Mô hình (model_list) - -> **Tính năng mới!** PicoClaw hiện sử dụng phương pháp cấu hình **đặt mô hình vào trung tâm**. Chỉ cần chỉ định dạng `nhà cung cấp/mô hình` (ví dụ: `zhipu/glm-4.7`) để thêm nhà cung cấp mới—**không cần thay đổi mã!** - -Thiết kế này cũng cho phép **hỗ trợ đa tác nhân** với lựa chọn nhà cung cấp linh hoạt: - -- **Tác nhân khác nhau, nhà cung cấp khác nhau** : Mỗi tác nhân có thể sử dụng nhà cung cấp LLM riêng -- **Mô hình dự phòng** : Cấu hình mô hình chính và dự phòng để tăng độ tin cậy -- **Cân bằng tải** : Phân phối yêu cầu trên nhiều endpoint khác nhau -- **Cấu hình tập trung** : Quản lý tất cả nhà cung cấp ở một nơi - -#### 📋 Tất cả Nhà cung cấp được Hỗ trợ - -| Nhà cung cấp | Prefix `model` | API Base Mặc định | Giao thức | Khóa API | -|-------------|----------------|-------------------|-----------|----------| -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Lấy Khóa](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Lấy Khóa](https://console.anthropic.com) | -| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Lấy Khóa](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Lấy Khóa](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Lấy Khóa](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Lấy Khóa](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Lấy Khóa](https://platform.moonshot.cn) | -| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Lấy Khóa](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Lấy Khóa](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (không cần khóa) | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Lấy Khóa](https://openrouter.ai/keys) | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Lấy Khóa](https://cerebras.ai) | -| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Lấy Khóa](https://console.volcengine.com) | -| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **Antigravity** | `antigravity/` | Google Cloud | Tùy chỉnh | Chỉ OAuth | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### Cấu hình Cơ bản - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "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.2" - } - } -} -``` - -#### Ví dụ theo Nhà cung cấp - -**OpenAI** -```json -{ - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_key": "sk-..." -} -``` - -**Zhipu AI (GLM)** -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**Anthropic (với OAuth)** -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "auth_method": "oauth" -} -``` -> Chạy `picoclaw auth login --provider anthropic` để thiết lập thông tin xác thực OAuth. - -**Proxy/API tùy chỉnh** -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -#### Cân bằng Tải tải - -Định cấu hình nhiều endpoint cho cùng một tên mô hình—PicoClaw sẽ tự động phân phối round-robin giữa chúng: - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.2", - "model": "openai/gpt-5.2", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### Chuyển đổi từ Cấu hình `providers` Cũ - -Cấu hình `providers` cũ đã **ngừng sử dụng** nhưng vẫn được hỗ trợ để tương thích ngược. - -**Cấu hình Cũ (đã ngừng sử dụng):** -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**Cấu hình Mới (khuyến nghị):** -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -Xem hướng dẫn chuyển đổi chi tiết tại [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). - -## 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 (cho bot chat) | -| `picoclaw status` | Hiển thị trạng thái | -| `picoclaw cron list` | Liệt kê tất cả tác vụ định kỳ | -| `picoclaw cron add ...` | Thêm tác vụ định kỳ | - -### 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**: "Remind me in 10 minutes" (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**: "Remind me every 2 hours" (Nhắc tôi mỗi 2 giờ) → kích hoạt mỗi 2 giờ -* **Biểu thức Cron**: "Remind me at 9am daily" (Nhắc tôi lúc 9 giờ sáng mỗi ngày) → sử dụng biểu thức cron - -Các tác vụ được lưu trong `~/.picoclaw/workspace/cron/` và được xử lý tự động. - -## 🤝 Đó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. 🤗 - -Lộ trình sắp được công bố... - -Nhóm phát triển đang được xây dựng. Điều kiện tham gia: Ít nhất 1 PR đã được merge. - -Nhóm người dùng: - -Discord: - -PicoClaw - -## 🐛 Xử lý sự cố - -### Tìm kiếm web hiện "API 配置问题" - -Điều này là bình thường nếu bạn chưa cấu hình API key cho tìm kiếm. PicoClaw sẽ cung cấp các liên kết hữu ích để tìm kiếm thủ công. - -Để bật tìm kiếm web: - -1. **Tùy chọn 1 (Khuyên dùng)**: Lấy API key miễn phí tại [https://brave.com/search/api](https://brave.com/search/api) (2000 truy vấn miễn phí/tháng) để có kết quả tốt nhất. -2. **Tùy chọn 2 (Không cần thẻ tín dụng)**: Nếu không có key, hệ thống tự động chuyển sang dùng **DuckDuckGo** (không cần key). - -Thêm key vào `~/.picoclaw/config.json` nếu dùng Brave: - -```json -{ - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -### Gặp lỗi lọc nội dung (Content Filtering) - -Một số nhà cung cấp (như Zhipu) có bộ lọc nội dung nghiêm ngặt. Thử diễn đạt lại câu hỏi hoặc sử dụng model khác. - -### Telegram bot báo "Conflict: terminated by other getUpdates" - -Điều này xảy ra khi có một instance bot khác đang chạy. Đảm bảo chỉ có một tiến trình `picoclaw gateway` chạy tại một thời điểm. - ---- - -## 📝 So sánh API Key - -| Dịch vụ | Gói miễn phí | Trường hợp sử dụng | -| --- | --- | --- | -| **OpenRouter** | 200K tokens/tháng | Đa model (Claude, GPT-4, v.v.) | -| **Zhipu** | 200K tokens/tháng | Tốt nhất cho người dùng Trung Quốc | -| **Brave Search** | 2000 truy vấn/tháng | Chức năng tìm kiếm web | -| **Groq** | Có gói miễn phí | Suy luận siêu nhanh (Llama, Mixtral) | diff --git a/README.zh.md b/README.zh.md index 8ce1ad2ee..98c8ffa4b 100644 --- a/README.zh.md +++ b/README.zh.md @@ -14,7 +14,7 @@ Twitter

-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md) +**中文** | [English](README.md) @@ -50,9 +50,16 @@ > - **注意:** picoclaw正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中 > - **注意:** picoclaw最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化. +## 📚 文档导航 + +推荐从统一入口快速定位文档： + +- 中文: [docs/README.zh.md](docs/README.zh.md) +- English: [docs/README.md](docs/README.md) + ## 📢 新闻 (News) -2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](docs/ROADMAP.md), 期待你的参与！ +2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](ROADMAP.md), 期待你的参与！ 2026-02-13 🎉 **PicoClaw 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 PicoClaw 的开发。 🚀 **行动号召：** 请在 GitHub Discussions 中提交您的功能请求 (Feature Requests)。我们将在接下来的周会上进行审查和优先级排序。 @@ -421,7 +428,7 @@ Agent 读取 HEARTBEAT.md | 提供商 | 用途 | 获取 API Key | | -------------------- | ---------------------------- | -------------------------------------------------------------------- | | `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) | +| `zhipu` | LLM (智谱直连) | [bigmodel.cn](https://bigmodel.cn) | | `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) | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..b267e6893 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,59 @@ +# Documentation Index + +PicoClaw documentation is maintained in **English** and **Chinese** only. + +## 1. Start Here + +| Topic | Document | Language | +| --- | --- | --- | +| Project overview and quick start | [../README.md](../README.md) | English | +| 项目总览与快速开始 | [../README.zh.md](../README.zh.md) | 中文 | +| Contribution guide | [../CONTRIBUTING.md](../CONTRIBUTING.md) | English | +| 贡献指南 | [../CONTRIBUTING.zh.md](../CONTRIBUTING.zh.md) | 中文 | +| Community roadmap | [../ROADMAP.md](../ROADMAP.md) | English | + +## 2. Channels / Messaging Integrations + +Most channel setup docs are currently in Chinese: + +| Channel | Document | +| --- | --- | +| Telegram | [channels/telegram/README.zh.md](channels/telegram/README.zh.md) | +| Discord | [channels/discord/README.zh.md](channels/discord/README.zh.md) | +| Slack | [channels/slack/README.zh.md](channels/slack/README.zh.md) | +| QQ | [channels/qq/README.zh.md](channels/qq/README.zh.md) | +| DingTalk | [channels/dingtalk/README.zh.md](channels/dingtalk/README.zh.md) | +| WeCom Bot | [channels/wecom/wecom_bot/README.zh.md](channels/wecom/wecom_bot/README.zh.md) | +| WeCom App | [channels/wecom/wecom_app/README.zh.md](channels/wecom/wecom_app/README.zh.md) | +| Feishu | [channels/feishu/README.zh.md](channels/feishu/README.zh.md) | +| LINE | [channels/line/README.zh.md](channels/line/README.zh.md) | +| OneBot | [channels/onebot/README.zh.md](channels/onebot/README.zh.md) | +| MaixCam | [channels/maixcam/README.zh.md](channels/maixcam/README.zh.md) | + +## 3. Providers and Tools + +| Topic | Document | Language | +| --- | --- | --- | +| Antigravity auth and integration | [ANTIGRAVITY_AUTH.md](ANTIGRAVITY_AUTH.md) | English | +| Antigravity provider usage | [ANTIGRAVITY_USAGE.md](ANTIGRAVITY_USAGE.md) | English | +| Tools configuration | [tools_configuration.md](tools_configuration.md) | English | +| 企业微信应用配置详解 | [wecom-app-configuration.md](wecom-app-configuration.md) | 中文 | + +## 4. Architecture and Design + +| Topic | Document | Language | +| --- | --- | --- | +| Provider architecture refactoring design | [design/provider-refactoring.md](design/provider-refactoring.md) | English | +| Provider refactoring test summary | [design/provider-refactoring-tests.md](design/provider-refactoring-tests.md) | English | +| Orchestration and audit runtime design | [design/orchestration-audit.md](design/orchestration-audit.md) | English | + +## 5. Migration + +| Topic | Document | Language | +| --- | --- | --- | +| From `providers` to `model_list` | [migration/model-list-migration.md](migration/model-list-migration.md) | English | + +## 6. Documentation Policy + +- Maintained languages: **English** and **Chinese** +- If you add or update major docs, keep EN/ZH navigation discoverable from top-level README files. diff --git a/docs/README.zh.md b/docs/README.zh.md new file mode 100644 index 000000000..f446b2a33 --- /dev/null +++ b/docs/README.zh.md @@ -0,0 +1,59 @@ +# 文档索引 + +PicoClaw 当前只维护 **中文** 与 **English** 两种文档语言。 + +## 1. 先看这里 + +| 主题 | 文档 | 语言 | +| --- | --- | --- | +| 项目总览与快速开始 | [../README.zh.md](../README.zh.md) | 中文 | +| Project overview and quick start | [../README.md](../README.md) | English | +| 贡献指南 | [../CONTRIBUTING.zh.md](../CONTRIBUTING.zh.md) | 中文 | +| Contribution guide | [../CONTRIBUTING.md](../CONTRIBUTING.md) | English | +| 社区路线图 | [../ROADMAP.md](../ROADMAP.md) | English | + +## 2. 渠道接入文档 + +当前大部分渠道接入文档为中文： + +| 渠道 | 文档 | +| --- | --- | +| Telegram | [channels/telegram/README.zh.md](channels/telegram/README.zh.md) | +| Discord | [channels/discord/README.zh.md](channels/discord/README.zh.md) | +| Slack | [channels/slack/README.zh.md](channels/slack/README.zh.md) | +| QQ | [channels/qq/README.zh.md](channels/qq/README.zh.md) | +| 钉钉 | [channels/dingtalk/README.zh.md](channels/dingtalk/README.zh.md) | +| 企业微信机器人 | [channels/wecom/wecom_bot/README.zh.md](channels/wecom/wecom_bot/README.zh.md) | +| 企业微信自建应用 | [channels/wecom/wecom_app/README.zh.md](channels/wecom/wecom_app/README.zh.md) | +| 飞书 | [channels/feishu/README.zh.md](channels/feishu/README.zh.md) | +| LINE | [channels/line/README.zh.md](channels/line/README.zh.md) | +| OneBot | [channels/onebot/README.zh.md](channels/onebot/README.zh.md) | +| MaixCam | [channels/maixcam/README.zh.md](channels/maixcam/README.zh.md) | + +## 3. Provider 与工具 + +| 主题 | 文档 | 语言 | +| --- | --- | --- | +| Antigravity 认证与接入 | [ANTIGRAVITY_AUTH.md](ANTIGRAVITY_AUTH.md) | English | +| Antigravity 使用说明 | [ANTIGRAVITY_USAGE.md](ANTIGRAVITY_USAGE.md) | English | +| 工具配置说明 | [tools_configuration.md](tools_configuration.md) | English | +| 企业微信应用配置详解 | [wecom-app-configuration.md](wecom-app-configuration.md) | 中文 | + +## 4. 架构设计 + +| 主题 | 文档 | 语言 | +| --- | --- | --- | +| Provider 架构重构设计 | [design/provider-refactoring.md](design/provider-refactoring.md) | English | +| Provider 重构测试总结 | [design/provider-refactoring-tests.md](design/provider-refactoring-tests.md) | English | +| 编排与审计运行时设计 | [design/orchestration-audit.md](design/orchestration-audit.md) | English | + +## 5. 迁移指南 + +| 主题 | 文档 | 语言 | +| --- | --- | --- | +| 从 `providers` 迁移到 `model_list` | [migration/model-list-migration.md](migration/model-list-migration.md) | English | + +## 6. 文档维护策略 + +- 维护语言仅限：**中文** 与 **English** +- 新增或更新核心文档时，请确保在顶层 README 中可被发现