-
- PicoClaw : Assistant IA Ultra-Efficace en Go
- -Matériel à 10$ · 10 Mo de RAM · Démarrage en 1s · 皮皮虾，我们走！
- -
- 
- 
-SipeedIO-black?style=flat&logo=x&logoColor=white){kind=icon}
-
-
-
-
|
-
- |
-
-
- |
-
-
-## 🦾 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'échelle | -Planifier • Automatiser • Mémoriser | -Découvrir • Analyser • Tendances | -
-
-### 🐜 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
-
-
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`
-
-### Variables d'Environnement
-
-Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de picoclaw en tant que service système. Ces variables sont indépendantes et contrôlent différents chemins.
-
-| Variable | Description | Chemin par Défaut |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Remplace le chemin du fichier de configuration. Cela indique directement à picoclaw quel `config.json` charger, en ignorant tous les autres emplacements. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME` | Remplace le répertoire racine des données picoclaw. Cela modifie l'emplacement par défaut du `workspace` et des autres répertoires de données. | `~/.picoclaw` |
-
-**Exemples :**
-
-```bash
-# Exécuter picoclaw en utilisant un fichier de configuration spécifique
-# Le chemin du workspace sera lu à partir de ce fichier de configuration
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Exécuter picoclaw avec toutes ses données stockées dans /opt/picoclaw
-# La configuration sera chargée à partir du fichier par défaut ~/.picoclaw/config.json
-# Le workspace sera créé dans /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Utiliser les deux pour une configuration entièrement personnalisée
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Structure du Workspace
-
-PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.picoclaw/workspace`) :
-
-```
-~/.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
-└── 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 audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
-
-| 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) |
-| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| `openrouter` (À 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) |
-
-
-
-## 🐛 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.) |
-| **Volcengine CodingPlan** | 9,9¥/premier mois | Idéal pour les utilisateurs chinois, multiples modèles SOTA (Doubao, DeepSeek, etc.) |
-| **Zhipu** | 200K tokens/mois | Convient aux utilisateurs chinois |
-| **Brave Search** | 2000 requêtes/mois | Fonctionnalité de recherche web |
-| **Groq** | Offre gratuite dispo | Inférence ultra-rapide (Llama, Mixtral) |
-
----
-
-
-
-
-
-
|
-
- |
-
-
- |
-
-
-
-## 🦾 デモンストレーション
-### 🛠️ スタンダードアシスタントワークフロー
-🧩 フルスタックエンジニア |
- 🗂️ ログ＆計画管理 |
- 🔎 Web 検索＆学習 |
-
|---|---|---|
|
-
|
-
|
-
| 開発 · デプロイ · スケール | -スケジュール · 自動化 · メモリ | -発見 · インサイト · トレンド | -
-
-
-## 🐛 トラブルシューティング
-
-### 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 など） |
-| **Volcengine CodingPlan** | 9.9元/初月 | 中国ユーザーに最適、複数のSOTAモデル（Doubao、DeepSeek等） |
-| **Zhipu** | 月 200K トークン | 中国ユーザーに適している |
-| **Qwen** | 無料枠あり | 通義千問 (Qwen) |
-| **Brave Search** | 月 2000 クエリ | Web 検索機能 |
-| **Tavily** | 月 1000 クエリ | AI エージェント検索最適化 |
-| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） |
-| **Cerebras** | 無料枠あり | 高速推論（Llama, Qwen など） |
-
----
-
-
-
-
-
-
-
|
-
- |
-
-
- |
-
-
-## 🦾 Demonstração
-
-### 🛠️ Fluxos de Trabalho Padrão do Assistente
-
-🧩 Engenharia Full-Stack |
-🗂️ Gerenciamento de Logs & Planejamento |
-🔎 Busca Web & Aprendizado |
-
|---|---|---|
|
-
|
-
|
-
| Desenvolver • Implantar • Escalar | -Agendar • Automatizar • Memorizar | -Descobrir • Analisar • Tendências | -
-
-### 🐜 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. Primeiro uso — gera docker/data/config.json automaticamente e para
-docker compose -f docker/docker-compose.yml --profile gateway up
-# O contêiner exibe "First-run setup complete." e para.
-
-# 3. Configure suas API keys
-vim docker/data/config.json # Chaves de API do provedor, tokens de bot, etc.
-
-# 4. Iniciar
-docker compose -f docker/docker-compose.yml --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`.
-
-```bash
-# 5. Ver logs
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-
-# 6. Parar
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
-
-### Modo Agente (Execução única)
-
-```bash
-# Fazer uma pergunta
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
-
-# Modo interativo
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### Atualizar
-
-```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
-```
-
-### 🚀 Início Rápido
-
-> [!TIP]
-> Configure sua API key em `~/.picoclaw/config.json`. Obtenha API keys: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Busca web é **opcional** — obtenha a [API Tavily](https://tavily.com) gratuita (1000 consultas grátis/mês) ou a [Brave Search API](https://brave.com/search/api) (2000 consultas grátis/mês).
-
-**1. Inicializar**
-
-```bash
-picoclaw onboard
-```
-
-**2. Configurar** (`~/.picoclaw/config.json`)
-
-```json
-{
- "model_list": [
- {
- "model_name": "ark-code-latest",
- "model": "volcengine/ark-code-latest",
- "api_key": "sk-your-api-key"
- },
- {
- "model_name": "gpt-5.4",
- "model": "openai/gpt-5.4",
- "api_key": "sk-your-openai-key",
- "request_timeout": 300,
- "api_base": "https://api.openai.com/v1"
- }
- ],
- "agents": {
- "defaults": {
- "model_name": "gpt-5.4"
- }
- },
- "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) |
-
- 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`
-
-### Variáveis de Ambiente
-
-Você pode substituir os caminhos padrão usando variáveis de ambiente. Isso é útil para instalações portáteis, implantações em contêineres ou para executar o picoclaw como um serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.
-
-| Variável | Descrição | Caminho Padrão |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Substitui o caminho para o arquivo de configuração. Isso informa diretamente ao picoclaw qual `config.json` carregar, ignorando todos os outros locais. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME` | Substitui o diretório raiz dos dados do picoclaw. Isso altera o local padrão do `workspace` e de outros diretórios de dados. | `~/.picoclaw` |
-
-**Exemplos:**
-
-```bash
-# Executar o picoclaw usando um arquivo de configuração específico
-# O caminho do workspace será lido de dentro desse arquivo de configuração
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Executar o picoclaw com todos os seus dados armazenados em /opt/picoclaw
-# A configuração será carregada do ~/.picoclaw/config.json padrão
-# O workspace será criado em /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Use ambos para uma configuração totalmente personalizada
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Estrutura do Workspace
-
-O PicoClaw armazena dados no workspace configurado (padrão: `~/.picoclaw/workspace`):
-
-```
-~/.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
-└── 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 áudio de qualquer canal serão automaticamente transcritas no nível do agente.
-
-| Provedor | Finalidade | Obter API Key |
-| --- | --- | --- |
-| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) |
-| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](bigmodel.cn) |
-| `volcengine` | LLM(Volcengine direto) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| `openrouter` (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) |
-
-
-
-## 🐛 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.) |
-| **Volcengine CodingPlan** | ¥9,9/primeiro mês | Ideal para usuários chineses, múltiplos modelos SOTA (Doubao, DeepSeek, etc.) |
-| **Zhipu** | 200K tokens/mês | Adequado 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) |
-
----
-
-
-
-
-
-
-
|
-
- |
-
-
- |
-
-
-## 🦾 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ộng | -Lên lịch • Tự động hóa • Ghi nhớ | -Khám phá • Phân tích • Xu hướng | -
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`
-
-### Biến môi trường
-
-Bạn có thể ghi đè các đường dẫn mặc định bằng cách sử dụng các biến môi trường. Điều này hữu ích cho việc cài đặt di động, triển khai container hóa hoặc chạy picoclaw như một dịch vụ hệ thống. Các biến này độc lập và kiểm soát các đường dẫn khác nhau.
-
-| Biến | Mô tả | Đường dẫn mặc định |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Ghi đè đường dẫn đến file cấu hình. Điều này trực tiếp yêu cầu picoclaw tải file `config.json` nào, bỏ qua tất cả các vị trí khác. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME` | Ghi đè thư mục gốc cho dữ liệu picoclaw. Điều này thay đổi vị trí mặc định của `workspace` và các thư mục dữ liệu khác. | `~/.picoclaw` |
-
-**Ví dụ:**
-
-```bash
-# Chạy picoclaw bằng một file cấu hình cụ thể
-# Đường dẫn workspace sẽ được đọc từ trong file cấu hình đó
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Chạy picoclaw với tất cả dữ liệu được lưu trữ trong /opt/picoclaw
-# Cấu hình sẽ được tải từ ~/.picoclaw/config.json mặc định
-# Workspace sẽ được tạo tại /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Sử dụng cả hai để có thiết lập tùy chỉnh hoàn toàn
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Cấu trúc Workspace
-
-PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`):
-
-```
-~/.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
-└── 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 âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển thành văn bản ở cấp độ agent.
-
-| 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) |
-| `volcengine` | LLM(Volcengine trực tiếp) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
-| `openrouter` (Đ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) |
-
-
-
-## 🐛 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.) |
-| **Volcengine CodingPlan** | ¥9.9/tháng đầu | Tốt nhất cho người dùng Trung Quốc, nhiều mô hình SOTA (Doubao, DeepSeek, v.v.) |
-| **Zhipu** | 200K tokens/tháng | Phù hợp 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) |
-
----
-
-
-
-
-
-
-
|
-
- |
-
-
- |
-
-
-## 🦾 演示
-
-### 🛠️ 标准助手工作流
-
-🧩 全栈工程师模式 |
-🗂️ 日志与规划管理 |
-🔎 网络搜索与学习 |
-
|---|---|---|
|
-
|
-
|
-
| 开发 • 部署 • 扩展 | -日程 • 自动化 • 记忆 | -发现 • 洞察 • 趋势 | -
-
-### 🐜 创新的低占用部署
-
-PicoClaw 几乎可以部署在任何 Linux 设备上！
-
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 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://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4)
-
-🌟 更多部署案例敬请期待！
-
-## 📦 安装
-
-### 使用预编译二进制文件安装
-
-从 [Release 页面](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. 首次运行 — 自动生成 docker/data/config.json 后退出
-docker compose -f docker/docker-compose.yml --profile gateway up
-# 容器打印 "First-run setup complete." 后自动停止
-
-# 3. 填写 API Key 等配置
-vim docker/data/config.json # 设置 provider API key、Bot Token 等
-
-# 4. 正式启动
-docker compose -f docker/docker-compose.yml --profile gateway up -d
-```
-
-> [!TIP]
-> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
-
-```bash
-# 5. 查看日志
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-
-# 6. 停止
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
-
-### Agent 模式 (一次性运行)
-
-```bash
-# 提问
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
-
-# 交互模式
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### 更新镜像
-
-```bash
-docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
-```
-
-### 🚀 快速开始
-
-> [!TIP]
-> 在 `~/.picoclaw/config.json` 中设置您的 API Key。获取 API Key: [火山引擎 (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)。网络搜索是 **可选的** — 获取免费的 [Tavily API](https://tavily.com) (每月 1000 次免费查询) 或 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询)。
-
-**1. 初始化 (Initialize)**
-
-```bash
-picoclaw onboard
-
-```
-
-**2. 配置 (Configure)** (`~/.picoclaw/config.json`)
-
-```json
-{
- "agents": {
- "defaults": {
- "workspace": "~/.picoclaw/workspace",
- "model_name": "gpt-5.4",
- "max_tokens": 8192,
- "temperature": 0.7,
- "max_tool_iterations": 20
- }
- },
- "model_list": [
- {
- "model_name": "ark-code-latest",
- "model": "volcengine/ark-code-latest",
- "api_key": "sk-your-api-key"
- },
- {
- "model_name": "gpt-5.4",
- "model": "openai/gpt-5.4",
- "api_key": "your-api-key",
- "request_timeout": 300
- },
- {
- "model_name": "claude-sonnet-4.6",
- "model": "anthropic/claude-sonnet-4.6",
- "api_key": "your-anthropic-key"
- }
- ],
- "tools": {
- "web": {
- "brave": {
- "enabled": false,
- "api_key": "YOUR_BRAVE_API_KEY",
- "max_results": 5
- },
- "tavily": {
- "enabled": false,
- "api_key": "YOUR_TAVILY_API_KEY",
- "max_results": 5
- }
- },
- "cron": {
- "exec_timeout_minutes": 5
- }
- }
-}
-```
-
-> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
-> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
-
-**3. 获取 API Key**
-
-* **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)
-* **网络搜索** (可选): [Tavily](https://tavily.com) - 专为 AI Agent 优化 (1000 请求/月) · [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月)
-
-> **注意**: 完整的配置模板请参考 `config.example.json`。
-
-**4. 对话 (Chat)**
-
-```bash
-picoclaw agent -m "2+2 等于几？"
-
-```
-
-就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。
-
----
-
-## 💬 聊天应用集成 (Chat Apps)
-
-PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
-
-> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。
-
-### 核心渠道
-
-| 渠道 | 设置难度 | 特性说明 | 文档链接 |
-| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Telegram** | ⭐ 简单 | 推荐，支持语音转文字，长轮询无需公网 | [查看文档](docs/channels/telegram/README.zh.md) |
-| **Discord** | ⭐ 简单 | Socket Mode，支持群组/私信，Bot 生态成熟 | [查看文档](docs/channels/discord/README.zh.md) |
-| **Slack** | ⭐ 简单 | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md) |
-| **Matrix** | ⭐⭐ 中等 | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](docs/channels/matrix/README.zh.md) |
-| **QQ** | ⭐⭐ 中等 | 官方机器人 API，适合国内社群 | [查看文档](docs/channels/qq/README.zh.md) |
-| **钉钉 (DingTalk)** | ⭐⭐ 中等 | Stream 模式无需公网，企业办公首选 | [查看文档](docs/channels/dingtalk/README.zh.md) |
-| **Line** | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook | [查看文档](docs/channels/line/README.zh.md) |
-| **OneBot** | ⭐⭐ 中等 | 兼容 NapCat/Go-CQHTTP，社区生态丰富 | [查看文档](docs/channels/onebot/README.zh.md) |
-| **MaixCam** | ⭐ 简单 | 专为 AI 摄像头设计的硬件集成通道 | [查看文档](docs/channels/maixcam/README.zh.md) |
-
-### Telegram 命令注册（启动时自动同步）
-
-PicoClaw 现在使用统一的命令定义来源。启动时会自动将 Telegram 支持的命令（例如 `/start`、`/help`、`/show`、`/list`）注册到 Bot 命令菜单，确保菜单展示与实际行为一致。
-Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行统一走 Agent Loop 中的 commands executor。
-
-如果注册因网络或 API 短暂异常失败，不会阻塞 channel 启动；系统会在后台自动重试。
-
-## 加入 Agent 社交网络
-
-只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
-
-\*\*阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)
-
-## ⚙️ 配置详解
-
-配置文件路径: `~/.picoclaw/config.json`
-
-### 环境变量
-
-你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
-
-| 变量 | 描述 | 默认路径 |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME` | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。 | `~/.picoclaw` |
-
-**示例：**
-
-```bash
-# 使用特定的配置文件运行 picoclaw
-# 工作区路径将从该配置文件中读取
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
-# 配置将从默认的 ~/.picoclaw/config.json 加载
-# 工作区将在 /opt/picoclaw/workspace 创建
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# 同时使用两者进行完全自定义设置
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### 工作区布局 (Workspace Layout)
-
-PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
-
-```
-~/.picoclaw/workspace/
-├── sessions/ # 对话会话和历史
-├── memory/ # 长期记忆 (MEMORY.md)
-├── state/ # 持久化状态 (最后一次频道等)
-├── cron/ # 定时任务数据库
-├── skills/ # 自定义技能
-├── AGENTS.md # Agent 行为指南
-├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次)
-├── IDENTITY.md # Agent 身份设定
-├── SOUL.md # Agent 灵魂/性格
-└── USER.md # 用户偏好
-
-```
-
-### 技能来源 (Skill Sources)
-
-默认情况下，技能会按以下顺序加载：
-
-1. `~/.picoclaw/workspace/skills`（工作区）
-2. `~/.picoclaw/skills`（全局）
-3. `
-
-## 🐛 疑难解答 (Troubleshooting)
-
-### 网络搜索提示 "API 配置问题"
-
-如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。
-
-启用网络搜索：
-
-1. 在 [https://tavily.com](https://tavily.com) (1000 次免费) 或 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (2000 次免费)
-2. 添加到 `~/.picoclaw/config.json`:
-
-```json
-{
- "tools": {
- "web": {
- "brave": {
- "enabled": false,
- "api_key": "YOUR_BRAVE_API_KEY",
- "max_results": 5
- },
- "duckduckgo": {
- "enabled": true,
- "max_results": 5
- }
- }
- }
-}
-```
-
-### 遇到内容过滤错误 (Content Filtering Errors)
-
-某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
-
-### Telegram bot 提示 "Conflict: terminated by other getUpdates"
-
-这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。
-
----
-
-## 📝 API Key 对比
-
-| 服务 | 免费层级 | 适用场景 |
-| --- | --- | --- |
-| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
-| **火山引擎 CodingPlan** | 9.9 元/首月 | 最适合国内用户，多种 SOTA 模型（豆包、DeepSeek 等） |
-| **智谱 (Zhipu)** | 200K tokens/月 | 适合中国用户 |
-| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
-| **Tavily** | 1000 次查询/月 | AI Agent 搜索优化 |
-| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
-| **LongCat** | 最多 5M tokens/天 | 推理速度快 (免费额度) |
-
----
-
-
-
- 
- 
