-## 🦾 Demonstracao
+## 🦾 Demonstração
-### 🛠️ Fluxos de Trabalho Padrao do Assistente
+### 🛠️ Fluxos de Trabalho Padrão do Assistente
-### 🐜 Implantacao Inovadora com Baixo Consumo
+### 🐜 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) versao E (Ethernet) ou W (WiFi6), para Assistente Domestico Minimalista
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) para Manutencao Automatizada de Servidores
+- $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 cenarios de implantacao aguardam voce!
+🌟 Mais cenários de implantação aguardam você!
-## 📦 Instalacao
+## 📦 Instalação
-### Instalar com binario pre-compilado
+### Instalar com binário pré-compilado
-Baixe o binario para sua plataforma na pagina de [releases](https://github.com/sipeed/picoclaw/releases).
+Baixe o binário para sua plataforma na página de [releases](https://github.com/sipeed/picoclaw/releases).
-### Instalar a partir do codigo-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
+### Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
```bash
git clone https://github.com/sipeed/picoclaw.git
@@ -157,7 +158,7 @@ make install
## 🐳 Docker Compose
-Voce tambem pode rodar o PicoClaw usando Docker Compose sem instalar nada localmente.
+Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada localmente.
```bash
# 1. Clone este repositorio
@@ -178,7 +179,7 @@ docker compose logs -f picoclaw-gateway
docker compose --profile gateway down
```
-### Modo Agente (Execucao unica)
+### Modo Agente (Execução única)
```bash
# Fazer uma pergunta
@@ -195,12 +196,12 @@ docker compose --profile gateway build --no-cache
docker compose --profile gateway up -d
```
-### 🚀 Inicio Rapido
+### 🚀 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 gratis/mes) ou use o fallback automatico integrado.
+> 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**
@@ -246,9 +247,9 @@ picoclaw onboard
**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 disponivel (2000 consultas/mes)
+* **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 configuracao completo.
+> **Nota**: Veja `config.example.json` para um modelo de configuração completo.
**4. Conversar**
@@ -256,21 +257,21 @@ picoclaw onboard
picoclaw agent -m "Quanto e 2+2?"
```
-Pronto! Voce tem um assistente de IA funcionando em 2 minutos.
+Pronto! Você tem um assistente de IA funcionando em 2 minutos.
---
-## 💬 Integracao com Apps de Chat
+## 💬 Integração com Apps de Chat
Converse com seu PicoClaw via Telegram, Discord, DingTalk ou LINE.
-| Canal | Nivel de Configuracao |
+| Canal | Nível de Configuração |
| --- | --- |
-| **Telegram** | Facil (apenas um token) |
-| **Discord** | Facil (bot token + intents) |
-| **QQ** | Facil (AppID + AppSecret) |
-| **DingTalk** | Medio (credenciais do app) |
-| **LINE** | Medio (credenciais + webhook URL) |
+| **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 unica mensagem via CLI ou qualquer App de Chat integrado.
+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 instrucoes para entrar no [ClawdChat.ai](https://clawdchat.ai)**
+**Leia `https://clawdchat.ai/skill.md` e siga as instruções para entrar no [ClawdChat.ai](https://clawdchat.ai)**
-## ⚙️ Configuracao Detalhada
+## ⚙️ Configuração Detalhada
-Arquivo de configuracao: `~/.picoclaw/config.json`
+Arquivo de configuração: `~/.picoclaw/config.json`
### Estrutura do Workspace
-O PicoClaw armazena dados no workspace configurado (padrao: `~/.picoclaw/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 # Descricao das ferramentas
-└── USER.md # Preferencias do usuario
+├── 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 Seguranca
+### 🔒 Sandbox de Segurança
-O PicoClaw roda em um ambiente sandbox por padrao. O agente so pode acessar arquivos e executar comandos dentro do workspace configurado.
+O PicoClaw roda em um ambiente sandbox por padrão. O agente so pode acessar arquivos e executar comandos dentro do workspace configurado.
-#### Configuracao Padrao
+#### Configuração Padrão
```json
{
@@ -516,16 +517,16 @@ O PicoClaw roda em um ambiente sandbox por padrao. O agente so pode acessar arqu
}
```
-| Opcao | Padrao | Descricao |
+| Opção | Padrão | Descrição |
|-------|--------|-----------|
-| `workspace` | `~/.picoclaw/workspace` | Diretorio de trabalho do agente |
+| `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 sao restritas ao sandbox:
+Quando `restrict_to_workspace: true`, as seguintes ferramentas são restritas ao sandbox:
-| Ferramenta | Funcao | Restricao |
+| Ferramenta | Função | Restrição |
|------------|--------|-----------|
| `read_file` | Ler arquivos | Apenas arquivos dentro do workspace |
| `write_file` | Escrever arquivos | Apenas arquivos dentro do workspace |
@@ -534,13 +535,13 @@ Quando `restrict_to_workspace: true`, as seguintes ferramentas sao restritas ao
| `append_file` | Adicionar a arquivos | Apenas arquivos dentro do workspace |
| `exec` | Executar comandos | Caminhos dos comandos devem estar dentro do workspace |
-#### Protecao Adicional do Exec
+#### Proteção Adicional do Exec
Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes comandos perigosos:
-* `rm -rf`, `del /f`, `rmdir /s` — Exclusao em massa
-* `format`, `mkfs`, `diskpart` — Formatacao de disco
-* `dd if=` — Criacao de imagem de disco
+* `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 `:(){ :|:& };:`
@@ -557,11 +558,11 @@ Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes com
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
```
-#### Desabilitar Restricoes (Risco de Seguranca)
+#### Desabilitar Restrições (Risco de Segurança)
-Se voce precisa que o agente acesse caminhos fora do workspace:
+Se você precisa que o agente acesse caminhos fora do workspace:
-**Metodo 1: Arquivo de configuracao**
+**Método 1: Arquivo de configuração**
```json
{
@@ -573,29 +574,29 @@ Se voce precisa que o agente acesse caminhos fora do workspace:
}
```
-**Metodo 2: Variavel de ambiente**
+**Método 2: Variável de ambiente**
```bash
export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
```
-> ⚠️ **Aviso**: Desabilitar esta restricao permite que o agente acesse qualquer caminho no seu sistema. Use com cuidado apenas em ambientes controlados.
+> ⚠️ **Aviso**: Desabilitar esta restrição permite que o agente acesse qualquer caminho no seu sistema. Use com cuidado apenas em ambientes controlados.
-#### Consistencia do Limite de Seguranca
+#### Consistência do Limite de Segurança
-A configuracao `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execucao:
+A configuração `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execução:
-| Caminho de Execucao | Limite de Seguranca |
+| Caminho de Execução | Limite de Segurança |
|----------------------|---------------------|
| Agente Principal | `restrict_to_workspace` ✅ |
-| Subagente / Spawn | Herda a mesma restricao ✅ |
-| Tarefas Heartbeat | Herda a mesma restricao ✅ |
+| Subagente / Spawn | Herda a mesma restrição ✅ |
+| Tarefas Heartbeat | Herda a mesma restrição ✅ |
-Todos os caminhos compartilham a mesma restricao de workspace — nao ha como contornar o limite de seguranca por meio de subagentes ou tarefas agendadas.
+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 Periodicas)
+### Heartbeat (Tarefas Periódicas)
-O PicoClaw pode executar tarefas periodicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace:
+O PicoClaw pode executar tarefas periódicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace:
```markdown
# Tarefas Periodicas
@@ -605,51 +606,51 @@ O PicoClaw pode executar tarefas periodicas automaticamente. Crie um arquivo `HE
- Verificar a previsao do tempo
```
-O agente lera este arquivo a cada 30 minutos (configuravel) e executara as tarefas usando as ferramentas disponiveis.
+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 duracao (busca web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**:
+Para tarefas de longa duração (busca web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**:
```markdown
-# Tarefas Periodicas
+# Tarefas Periódicas
-## Tarefas Rapidas (resposta direta)
+## Tarefas Rápidas (resposta direta)
- Informar hora atual
## Tarefas Longas (usar spawn para async)
-- Buscar noticias de IA na web e resumir
+- Buscar notícias de IA na web e resumir
- Verificar email e reportar mensagens importantes
```
**Comportamentos principais:**
-| Funcionalidade | Descricao |
+| Funcionalidade | Descrição |
|----------------|-----------|
-| **spawn** | Cria subagente assincrono, nao bloqueia o heartbeat |
-| **Contexto independente** | Subagente tem seu proprio contexto, sem historico de sessao |
-| **Ferramenta message** | Subagente se comunica diretamente com o usuario via ferramenta message |
-| **Nao-bloqueante** | Apos o spawn, o heartbeat continua para a proxima tarefa |
+| **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 Comunicacao do Subagente
+#### Como Funciona a Comunicação do Subagente
```
Heartbeat dispara
↓
-Agente le HEARTBEAT.md
+Agente lê HEARTBEAT.md
↓
Para tarefa longa: spawn subagente
↓ ↓
-Continua proxima tarefa Subagente trabalha independentemente
+Continua próxima tarefa Subagente trabalha independentemente
↓ ↓
-Todas tarefas concluidas Subagente usa ferramenta "message"
+Todas tarefas concluídas Subagente usa ferramenta "message"
↓ ↓
-Responde HEARTBEAT_OK Usuario recebe resultado diretamente
+Responde HEARTBEAT_OK Usuário recebe resultado diretamente
```
-O subagente tem acesso as ferramentas (message, web_search, etc.) e pode se comunicar com o usuario independentemente sem passar pelo agente principal.
+O subagente tem acesso às ferramentas (message, web_search, etc.) e pode se comunicar com o usuário independentemente sem passar pelo agente principal.
-**Configuracao:**
+**Configuração:**
```json
{
@@ -660,12 +661,12 @@ O subagente tem acesso as ferramentas (message, web_search, etc.) e pode se comu
}
```
-| Opcao | Padrao | Descricao |
+| Opção | Padrão | Descrição |
|-------|--------|-----------|
| `enabled` | `true` | Habilitar/desabilitar heartbeat |
-| `interval` | `30` | Intervalo de verificacao em minutos (min: 5) |
+| `interval` | `30` | Intervalo de verificação em minutos (min: 5) |
-**Variaveis de ambiente:**
+**Variáveis de ambiente:**
* `PICOCLAW_HEARTBEAT_ENABLED=false` para desabilitar
* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
@@ -673,7 +674,7 @@ O subagente tem acesso as ferramentas (message, web_search, etc.) e pode se comu
### Provedores
> [!NOTE]
-> O Groq fornece transcricao de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serao automaticamente transcritas.
+> 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 |
| --- | --- | --- |
@@ -683,10 +684,10 @@ O subagente tem acesso as ferramentas (message, web_search, etc.) e pode se comu
| `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) |
-| `groq` | LLM + **Transcricao de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
+| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
-## 🐛 Solucao de Problemas
+## 🐛 Solução de Problemas
### Busca web mostra "API 配置问题"
-Isso e normal se voce ainda nao configurou uma API key de busca. O PicoClaw fornecera links uteis para busca manual.
+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. **Opcao 1 (Recomendado)**: Obtenha uma API key gratuita em [https://brave.com/search/api](https://brave.com/search/api) (2000 consultas gratis/mes) para os melhores resultados.
-2. **Opcao 2 (Sem Cartao de Credito)**: Se voce nao tem uma key, o sistema automaticamente usa o **DuckDuckGo** como fallback (sem necessidade de key).
+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:
@@ -861,21 +862,21 @@ Adicione a key em `~/.picoclaw/config.json` se usar o Brave:
}
```
-### Erros de filtragem de conteudo
+### Erros de filtragem de conteúdo
-Alguns provedores (como Zhipu) possuem filtragem de conteudo. Tente reformular sua pergunta ou use um modelo diferente.
+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 instancia do bot esta rodando. Certifique-se de que apenas um `picoclaw gateway` esteja rodando por vez.
+Isso acontece quando outra instância do bot está em execução. Certifique-se de que apenas um `picoclaw gateway` esteja rodando por vez.
---
-## 📝 Comparacao de API Keys
+## 📝 Comparação de API Keys
-| Servico | Plano Gratuito | Caso de Uso |
+| Serviço | Plano Gratuito | Caso de Uso |
| --- | --- | --- |
-| **OpenRouter** | 200K tokens/mes | Multiplos modelos (Claude, GPT-4, etc.) |
-| **Zhipu** | 200K tokens/mes | Melhor para usuarios chineses |
-| **Brave Search** | 2000 consultas/mes | Funcionalidade de busca web |
-| **Groq** | Plano gratuito disponivel | Inferencia ultra-rapida (Llama, Mixtral) |
+| **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) |