Skip to content

Latest commit

 

History

History
882 lines (659 loc) · 26.4 KB

File metadata and controls

882 lines (659 loc) · 26.4 KB
PicoClaw

PicoClaw: Assistente de IA Ultra-Eficiente em Go

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

Go Hardware License
Website Twitter

中文 | 日本語 | Português | Tiếng Việt | Français | English


🦐 PicoClaw é um assistente pessoal de IA ultra-leve inspirado no 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, e o site da empresa é o 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 — 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 • Escalar Agendar • Automatizar • Memorizar Descobrir • 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
# 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 versão E (Ethernet) ou W (WiFi6), para Assistente Doméstico Minimalista
  • $30~50 NanoKVM, ou $100 NanoKVM-Pro para Manutenção Automatizada de Servidores
  • $50 MaixCAM ou $100 MaixCAM2 para Monitoramento Inteligente
picoclaw_detect_person.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.

Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)

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.

# 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

# 4. Ver logs
docker compose logs -f picoclaw-gateway

# 5. Parar
docker compose --profile gateway down

Modo Agente (Execução única)

# Fazer uma pergunta
docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"

# Modo interativo
docker compose run --rm picoclaw-agent

Rebuild

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 (LLM) · Zhipu (LLM) Busca web e opcional — obtenha a Brave Search API gratuita (2000 consultas grátis/mês) ou use o fallback automático integrado.

1. Inicializar

picoclaw onboard

2. Configurar (~/.picoclaw/config.json)

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "xxx",
      "api_base": "https://openrouter.ai/api/v1"
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    }
  }
}

3. Obter API Keys

Nota: Veja config.example.json para um modelo de configuração completo.

4. Conversar

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 ou LINE.

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)
Telegram (Recomendado)

1. Criar o bot

  • Abra o Telegram, busque @BotFather
  • Envie /newbot, siga as instruções
  • Copie o token

2. Configurar

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}

Obtenha seu User ID pelo @userinfobot no Telegram.

3. Executar

picoclaw gateway
Discord

1. Criar o 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

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["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

picoclaw gateway
QQ

1. Criar o bot

2. Configurar

{
  "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

picoclaw gateway
DingTalk

1. Criar o bot

  • Acesse a Open Platform
  • Crie um app interno
  • Copie o Client ID e Client Secret

2. Configurar

{
  "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

picoclaw gateway
LINE

1. Criar uma Conta Oficial LINE

  • Acesse o LINE Developers Console
  • Crie um provider → Crie um canal Messaging API
  • Copie o Channel Secret e o Channel Access Token

2. Configurar

{
  "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:

# 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

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.

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

⚙️ 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

{
  "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

{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}

Método 2: Variável de ambiente

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:

# 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:

# 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:

{
  "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
zhipu LLM (Zhipu direto) bigmodel.cn
openrouter (Em teste) LLM (recomendado, acesso a todos os modelos) openrouter.ai
anthropic (Em teste) LLM (Claude direto) console.anthropic.com
openai (Em teste) LLM (GPT direto) platform.openai.com
deepseek (Em teste) LLM (DeepSeek direto) platform.deepseek.com
groq LLM + Transcrição de voz (Whisper) console.groq.com
Configuração Zhipu

1. Obter API key

2. Configurar

{
  "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

picoclaw agent -m "Ola, como vai?"
Exemplo de configuraçao completa
{
  "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
  }
}

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: https://discord.gg/V4sAZ9XWpN

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 (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:

{
  "tools": {
    "web": {
      "brave": {
        "enabled": true,
        "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)