⚙️ Guia de Configuração

Voltar ao README

⚙️ Configuração

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 execução do picoclaw como serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.

Exemplos:

# Executar 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 picoclaw com todos os dados armazenados em /opt/picoclaw
# A configuração será carregada do padrão ~/.picoclaw/config.json
# O workspace será criado em /opt/picoclaw/workspace
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# Usar ambos para uma configuração totalmente personalizada
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

Nível de Log do Gateway

gateway.log_level controla a verbosidade dos logs do Gateway, configurável em config.json:

{
  "gateway": {
    "log_level": "warn"
  }
}

O valor padrão é warn. Valores suportados: debug, info, warn, error, fatal.

Também pode ser substituído pela variável de ambiente: PICOCLAW_LOG_LEVEL=info

Layout do Workspace

O PicoClaw armazena dados no seu workspace configurado (padrão: ~/.picoclaw/workspace):

~/.picoclaw/workspace/
├── sessions/          # Sessões de conversa e histórico
├── memory/           # Memória de longo prazo (MEMORY.md)
├── state/            # Estado persistente (último canal, etc.)
├── cron/             # Banco de dados de tarefas agendadas
├── skills/           # Skills personalizadas
├── AGENT.md          # Guia de comportamento do agente
├── HEARTBEAT.md      # Prompts de tarefas periódicas (verificados a cada 30 min)
├── IDENTITY.md       # Identidade do agente
├── SOUL.md           # Alma do agente
└── USER.md           # Preferências do usuário

Nota: Alterações em AGENT.md, SOUL.md, USER.md e memory/MEMORY.md são detectadas automaticamente em tempo de execução via rastreamento de data de modificação (mtime). Não é necessário reiniciar o gateway após editar esses arquivos — o agente carrega o novo conteúdo na próxima requisição.

Fontes de Skills

Por padrão, as skills são carregadas de:

1. ~/.picoclaw/workspace/skills (workspace)
2. ~/.picoclaw/skills (global)
3. <caminho-embutido-na-compilação>/skills (embutido)

Para configurações avançadas/de teste, você pode substituir o diretório raiz de skills builtin com:

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

Usando Skills e Comandos em Canais de Chat

Depois que as skills estiverem instaladas, voce pode inspeciona-las e aplica-las diretamente de um canal de chat:

• /list skills mostra os nomes das skills instaladas visiveis para o agente atual.
• /use <skill> <message> força uma skill para uma unica requisicao.
• /use <skill> prepara essa skill para a sua proxima mensagem no mesmo chat.
• /use clear cancela uma substituicao pendente criada por /use <skill>.
• /btw <question> faz uma pergunta lateral imediata sem alterar o historico atual da sessao. /btw e tratado como uma consulta direta sem ferramentas e nao entra no fluxo normal de execucao de ferramentas.

Exemplos:

/list skills
/use git explique como fazer squash dos ultimos 3 commits
/btw me relembre o que ja decidimos sobre o plano de deploy
/use italiapersonalfinance
dammi le ultime news

Política Unificada de Execução de Comandos

• Comandos slash genéricos são executados através de um único caminho em pkg/agent/loop.go via commands.Executor.
• Os adaptadores de canal não consomem mais comandos genéricos localmente; eles encaminham o texto de entrada para o caminho bus/agent. O Telegram ainda registra automaticamente na inicialização comandos suportados como /start, /help, /show, /list, /use e /btw.
• Comando slash desconhecido (por exemplo /foo) passa para o processamento normal do LLM.
• Comando registrado mas não suportado no canal atual (por exemplo /show no WhatsApp) retorna um erro explícito ao usuário e interrompe o processamento.

🔒 Sandbox de Segurança

O PicoClaw é executado em um ambiente sandbox por padrão. O agente só pode acessar arquivos e executar comandos dentro do workspace configurado.

Configuração Padrão

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

Ferramentas Protegidas

Quando restrict_to_workspace: true, as seguintes ferramentas são isoladas:

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= — Imagem de disco
• Escrita em /dev/sd[a-z] — Escritas diretas em disco
• shutdown, reboot, poweroff — Desligamento do sistema
• Fork bomb :(){ :|:& };:

Controle de Acesso a Arquivos

Segurança do Exec

Nota de Segurança: A proteção contra symlinks é habilitada por padrão — todos os caminhos de arquivo são resolvidos através de filepath.EvalSymlinks antes da correspondência com a whitelist, prevenindo ataques de escape via symlink.

Limitação Conhecida: Processos Filhos de Ferramentas de Build

O guard de segurança do exec inspeciona apenas a linha de comando que o PicoClaw executa diretamente. Ele não inspeciona recursivamente processos filhos gerados por ferramentas de desenvolvimento permitidas como make, go run, cargo, npm run ou scripts de build personalizados.

Isso significa que um comando de nível superior ainda pode compilar ou executar outros binários após passar pela verificação inicial do guard. Na prática, trate scripts de build, Makefiles, scripts de pacotes e binários gerados como código executável que precisa do mesmo nível de revisão que um comando shell direto.

Para ambientes de maior risco:

• Revise scripts de build antes da execução.
• Prefira aprovação/revisão manual para fluxos de trabalho de compilação e execução.
• Execute o PicoClaw dentro de um contêiner ou VM se precisar de isolamento mais forte do que o guard integrado oferece.

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)}

Desabilitando Restrições (Risco de Segurança)

Se você precisar 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 cautela 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:

Todos os caminhos compartilham a mesma restrição de workspace — não há como contornar o limite de segurança através 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 Periódicas

- Verificar meu e-mail para mensagens importantes
- Revisar meu calendário para eventos próximos
- Verificar a previsão do tempo

O agente lerá este arquivo a cada 30 minutos (configurável) e executará quaisquer tarefas usando as ferramentas disponíveis.

Tarefas Assíncronas com Spawn

Para tarefas de longa duração (busca na web, chamadas de API), use a ferramenta spawn para criar um subagente:

# Tarefas Periódicas

## Tarefas Rápidas (responder diretamente)

- Informar a hora atual

## Tarefas Longas (usar spawn para assíncrono)

- Pesquisar notícias de IA na web e resumir
- Verificar e-mails e reportar mensagens importantes

Comportamentos principais:

Fluxo de Comunicação do Subagente

Heartbeat disparado
    ↓
Agent lê HEARTBEAT.md
    ↓
Tarefa longa: spawn subagente
    ↓                           ↓
Continua próxima tarefa    Subagente trabalha independentemente
    ↓                           ↓
Todas tarefas concluídas   Subagente usa ferramenta "message"
    ↓                           ↓
Responde HEARTBEAT_OK      Usuário recebe resultado diretamente

Configuração:

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

Variáveis de ambiente:

• PICOCLAW_HEARTBEAT_ENABLED=false para desativar
• PICOCLAW_HEARTBEAT_INTERVAL=60 para alterar o intervalo

Providers

[!NOTE] O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.

Configuração de Modelos (model_list)

Novidade: PicoClaw agora usa uma abordagem centrada no modelo. Basta especificar o formato vendor/model (ex.: zhipu/glm-4.7) para adicionar novos providers — sem alterações de código!

Todos os Vendors Suportados

Balanceamento de Carga

Configure múltiplos endpoints para o mesmo nome de modelo — PicoClaw fará round-robin automaticamente:

{
  "model_list": [
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_keys": ["sk-key1"] },
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_keys": ["sk-key2"] }
  ]
}

Migração da Configuração Legada providers

A configuração antiga providers está depreciada e foi removida no V2. Configs V0/V1 existentes são auto-migradas. Veja docs/migration/model-list-migration.md.

Arquitetura de Providers

PicoClaw roteia providers por família de protocolo:

• Compatível com OpenAI: OpenRouter, Groq, Zhipu, endpoints vLLM e a maioria dos outros.
• Gemini nativo: Google Gemini via endpoints nativos models/*:generateContent e models/*:streamGenerateContent.
• Anthropic: Comportamento nativo da API Claude.
• Codex/OAuth: Rota de autenticação OAuth/token OpenAI.

Isso mantém o runtime leve enquanto torna novos backends compatíveis com OpenAI basicamente uma operação de configuração (api_base + api_keys).

Tarefas Agendadas / Lembretes

PicoClaw suporta tarefas agendadas via ferramenta cron.

{
  "tools": {
    "cron": {
      "enabled": true,
      "exec_timeout_minutes": 5
    }
  }
}

As tarefas agendadas persistem após reinicializações em ~/.picoclaw/workspace/cron/.

Tópicos Avançados