picoclaw/docs/guides/configuration.pt-br.md

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

Variável	Descrição	Caminho Padrão
PICOCLAW_CONFIG	Substitui o caminho para o arquivo de configuração. Isso indica diretamente ao picoclaw qual config.json carregar, ignorando todos os outros locais.	~/.picoclaw/config.json
PICOCLAW_HOME	Substitui o diretório raiz para dados do picoclaw. Isso altera o local padrão do workspace e outros diretórios de dados.	~/.picoclaw

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.

Política de contexto da requisição

turn_profile é uma política opcional em agents.defaults.turn_profile para controlar qual contexto cada novo turno carrega: histórico, prompt de sistema, prompts de skills e ferramentas permitidas. Sem essa configuração, ou com "enabled": false, o PicoClaw mantém o comportamento normal. Com "enabled": true, a política abaixo se aplica a cada novo turno.

Todos os blocos usam os mesmos valores de mode:

Mode	Significado
default	Mantém o comportamento normal do PicoClaw. Blocos ausentes ou sem mode são tratados como default.
off	Desativa esse bloco para o turno.
custom	Usa uma lista de permissão. Nesta versão, custom só é suportado para skills e tools; usá-lo em history ou system_prompt gera erro de validação.

Blocos disponíveis:

Bloco	O que controla
history	Leitura de histórico e resumo, gravação de mensagens de usuário/assistente/ferramenta, ingestão de contexto, compactação e resumo.
system_prompt	Injeção da identidade padrão do PicoClaw, instruções do workspace, memória, contexto de execução e resumo. Prompts de sistema externos ainda são permitidos quando este bloco está off.
skills	Catálogo de skills e conteúdo de skills ativas no prompt. custom.allow mantém apenas os nomes listados.
tools	Ferramentas visíveis ao modelo e permitidas na execução. custom.allow mantém apenas ferramentas registradas e listadas.

Quando system_prompt.mode é off, ferramentas continuam visíveis e nenhum prompt de sistema externo é fornecido, o PicoClaw reutiliza sua regra existente de uso de ferramentas como prompt mínimo de fallback. Se tools.mode é off, esse fallback não é adicionado.

Exemplo de contexto limpo com ferramentas web:

{
  "agents": {
    "defaults": {
      "turn_profile": {
        "enabled": true,
        "history": { "mode": "off" },
        "system_prompt": { "mode": "off" },
        "skills": { "mode": "off" },
        "tools": {
          "mode": "custom",
          "allow": ["web_search", "web_fetch"]
        }
      }
    }
  }
}

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

Opção	Padrão	Descrição
workspace	~/.picoclaw/workspace	Diretório de trabalho do agente
restrict_to_workspace	true	Restringir acesso a arquivos/comandos ao workspace

Ferramentas Protegidas

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

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 diretórios	Apenas diretórios dentro do workspace
edit_file	Editar arquivos	Apenas arquivos dentro do workspace
append_file	Anexar a arquivos	Apenas arquivos dentro do workspace
exec	Executar comandos	Caminhos de comando 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= — 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

Config Key	Type	Default	Description
tools.allow_read_paths	string[]	[]	Additional paths allowed for reading outside workspace
tools.allow_write_paths	string[]	[]	Additional paths allowed for writing outside workspace

Segurança do Exec

Config Key	Type	Default	Description
tools.exec.allow_remote	bool	false	Allow exec tool from remote channels (Telegram/Discord etc.)
tools.exec.enable_deny_patterns	bool	true	Enable dangerous command interception
tools.exec.custom_deny_patterns	string[]	[]	Custom regex patterns to block
tools.exec.custom_allow_patterns	string[]	[]	Custom regex patterns to allow

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:

Caminho de Execução	Limite de Segurança
Main Agent	restrict_to_workspace ✅
Subagent / Spawn	Herda a mesma restrição ✅
Heartbeat tasks	Herda a mesma restriçã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:

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
message tool	Subagente comunica diretamente com o usuário via message tool
Não-bloqueante	Após o spawn, o heartbeat continua para a próxima tarefa

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

Opção	Padrão	Descrição
enabled	true	Ativar/desativar heartbeat
interval	30	Intervalo em minutos (mínimo: 5)

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.

Provider	Finalidade	Obter API Key
gemini	LLM (Gemini direto)	aistudio.google.com
zhipu	LLM (Zhipu direto)	bigmodel.cn
volcengine	LLM (Volcengine direto)	volcengine.com
openrouter	LLM (recomendado, acesso a todos modelos)	openrouter.ai
anthropic	LLM (Claude direto)	console.anthropic.com
openai	LLM (GPT direto)	platform.openai.com
deepseek	LLM (DeepSeek direto)	platform.deepseek.com
qwen	LLM (Qwen direto)	dashscope.console.aliyun.com
groq	LLM + Transcrição de voz (Whisper)	console.groq.com
cerebras	LLM (Cerebras direto)	cerebras.ai
vivgrid	LLM (Vivgrid direto)	vivgrid.com

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

Vendor	Prefixo model	API Base padrão	Protocolo	API Key
OpenAI	openai/	https://api.openai.com/v1	OpenAI	Obter
Anthropic	anthropic/	https://api.anthropic.com/v1	Anthropic	Obter
智谱 AI (GLM)	zhipu/	https://open.bigmodel.cn/api/paas/v4	OpenAI	Obter
DeepSeek	deepseek/	https://api.deepseek.com/v1	OpenAI	Obter
Google Gemini	gemini/	https://generativelanguage.googleapis.com/v1beta	Gemini	Obter
Groq	groq/	https://api.groq.com/openai/v1	OpenAI	Obter
通义千问 (Qwen)	qwen/	https://dashscope.aliyuncs.com/compatible-mode/v1	OpenAI	Obter
Ollama	ollama/	http://localhost:11434/v1	OpenAI	Local (sem chave)
OpenRouter	openrouter/	https://openrouter.ai/api/v1	OpenAI	Obter
VolcEngine (Doubao)	volcengine/	https://ark.cn-beijing.volces.com/api/v3	OpenAI	Obter
Antigravity	antigravity/	Google Cloud	Custom	Somente OAuth

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.

Configuração de Streaming

O streaming do provider usa double opt-in e fica desativado por padrão. O agent só tenta streaming quando o canal atual tem settings.streaming.enabled: true, a entrada de modelo ativa tem streaming.enabled: true, e tanto o provider quanto o canal suportam streaming. Se qualquer condição estiver ausente, o PicoClaw usa o caminho normal de requisição sem streaming.

O Pico WebUI é o primeiro canal totalmente integrado. O Pico cria a primeira mensagem assistant com o wire message existente message.create e depois atualiza a mesma mensagem com message.update; nenhum novo tipo de wire message do Pico é introduzido.

Deixe streaming ausente quando não quiser streaming. Um bloco streaming omitido significa desativado; você não precisa escrever "streaming": {"enabled": false}.

Exemplo de ativação:

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_keys": ["sk-your-openai-key"],
      "streaming": {
        "enabled": true
      }
    }
  ],
  "channel_list": {
    "pico": {
      "enabled": true,
      "type": "pico",
      "settings": {
        "token": "YOUR_PICO_TOKEN",
        "streaming": {
          "enabled": true
        }
      }
    }
  }
}

Campo	Tipo	Padrão	Descrição
channel_list.<name>.settings.streaming.enabled	bool	false	Permite que este canal exiba output streaming do provider
channel_list.<name>.settings.streaming.throttle_seconds	int	Padrão do Pico após ativar: 0	Intervalo mínimo entre atualizações intermediárias; o conteúdo final sempre é enviado
channel_list.<name>.settings.streaming.min_growth_chars	int	Padrão do Pico após ativar: 1	Crescimento mínimo de texto antes de enviar outra atualização intermediária; o conteúdo final sempre é enviado
model_list[].streaming.enabled	bool	false	Permite que esta entrada de modelo tente requisições de provider streaming

As variáveis de ambiente legadas do Telegram continuam compatíveis: PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED, PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS e PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS. Elas se aplicam apenas às settings do Telegram e não ativam nem modificam settings.streaming do Pico.

O comportamento de falha é intencionalmente conservador: se o streaming falhar antes de qualquer chunk visível ser enviado, o PicoClaw tenta novamente uma vez pelo caminho normal Chat(). Se um chunk já foi mostrado ao usuário, o PicoClaw não envia uma segunda resposta sem streaming, evitando output duplicado.

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

Tópico	Descrição
Sistema de Hooks	Hooks orientados a eventos: observadores, interceptores, hooks de aprovação
Steering	Injetar mensagens em um loop de agente em execução
SubTurn	Coordenação de subagentes, controle de concorrência, ciclo de vida
Gerenciamento de Contexto	Detecção de limites de contexto, compressão