Módulo 4.2: Agentes, skills, custo e o que vem | openpcbot v3: seu Jarvis local

🤖 Um agente é uma pasta

Cada subpasta de agents/ com um agent.yaml vira um agente no registry. Pasta que começa com _ é ignorada, por isso agents/_template serve de modelo sem virar agente. O prompt do agente é o CLAUDE.md da pasta (ou AGENT.md, ou prompt.md), limitado aos primeiros 6.000 caracteres.

Legenda: só o primeiro arquivo é obrigatório. Como o registry lê a pasta no boot, qualquer mudança aqui pede restart do serviço.

Chave	O que faz	Padrão
`name` · `description`	nome e o que o agente faz; a descrição é o que o roteador lê para escolher	nome da pasta
`model`	vira um alias da CLI: `opus`, `haiku`, `fable` ou `sonnet`	`sonnet`
`effort`	esforço declarado para aquele agente	`medium`
`read_only`	`true` faz especialista que só lê; o agente `research` é só leitura pelo próprio nome	`false`
`cwd`	diretório onde o `claude -p` roda	a sua pasta `projetos`
`mcp_config`	JSON de servidores MCP só dele (módulo 4.1)	herda os do usuário

Legenda: o model do arquivo pode ser um id completo, como claude-opus-5 nos quatro agentes que já vêm: o registry reduz ao alias antes de chamar a CLI. Os agentes instalados são comms, content, ops e research, mais um lead genérico com escrita que assume quando nenhum especialista cabe.

✦ Dica prática

O desenho é N especialistas só leitura em paralelo mais um lead com escrita. Quando criar um agente novo, comece por agents/_template/agent.yaml.example, copie a pasta, renomeie e decida primeiro o read_only. Dar escrita a um agente de pesquisa é o erro que custa caro, e nenhum dos outros campos protege contra ele.

🧰 Skills: só a metadata entra no prompt

Novo aqui? Uma skill é uma receita escrita em texto: um arquivo skills/<id>/SKILL.md que começa com um cabeçalho de duas linhas, name e description, e depois explica o passo a passo. Só o cabeçalho entra no prompt; o corpo é lido sob demanda por quem vai executar. A regra veio do estudo de uso de tokens do openclaw.

skills/tldr/SKILL.md (início do arquivo real)

--- name: tldr description: Save a summary of this conversation to the vault. Key decisions, things to remember, next actions. Store in the right folder automatically. --- # TL;DR, resumo da sessão (o corpo continua e NÃO entra no prompt)

Legenda: as duas primeiras linhas custam tokens em toda mensagem; o resto custa zero até alguém decidir usar a skill. Por isso a descrição é a parte que precisa estar bem escrita.

✓ O que FAZER

✓Escrever a description dizendo quando usar, não só o que faz.
✓Conferir o que está instalado com /skills: são as 15 herdadas do v2, copiadas como estão.
✓Olhar skills/_rascunhos/ de vez em quando: é o loop de aprendizado guardando propostas.
✓Deixar o passo a passo longo no corpo do arquivo, que é barato.

✗ O que NÃO fazer

✗Encher a description de detalhe operacional: isso é overhead fixo em toda chamada.
✗Esperar que um rascunho vire skill sozinho: aprovar rascunho depende da decisão 6 do plano e ainda não existe como comando.
✗Criar arquivo sem o campo name: sem ele o registry ignora a skill.
✗Contar com verificação de saúde das skills: /skills hoje só lista.

As 15 skills que vieram do v2 cobrem vídeo, transcrição, agenda, Gmail, Slack, música, resumo de sessão e organização do vault. Pastas que começam com _ ficam de fora da listagem normal, como em agents/.

💰 Custo: tiers, preços e trava

Toda chamada de modelo passa por src/custo/gateway.ts, inclusive as de embedding. A ordem é sempre a mesma: checa orçamento, escolhe o provedor pelo tier, faz preflight de RAM se for local, chama, mede a latência, calcula o custo e grava em chamadas_llm. Não existe caminho paralelo, e é isso que faz o /usage ser confiável.

Tier	Provedor e modelo	Quando entra
`local`	Ollama, `qwen3.8:27b`	padrão de tudo; custo zero
`barato`	OpenRouter, `claude-haiku-4.5`	raciocínio longo em resposta direta, ou quando falta RAM para o Ollama
`premium`	`claude -p` pela CLI, sonnet ou opus por agente	rota de agente; o custo real vem do próprio CLI

Legenda: config/precos.yaml guarda o valor em dólar por 1 milhão de tokens, com entrada, saída e cache, para os modelos usados. Quando o OpenRouter devolve o custo real, é ele que vale; a tabela cobre o resto. Subir de tier registra o motivo.

⌘ Copiar e rodar: definir o teto do mês

Objetivo: ver o gasto atual e ajustar o orçamento. O valor do .env vence o do YAML.

# no chat
/usage

# no arquivo config/orcamento.yaml
mensal_usd: 50
aviso_pct: 70
trava_pct: 100

# ou no .env do v3, que sobrescreve o YAML
ORCAMENTO_MENSAL_USD=<o-teto-que-voce-quer>

Como verificar: depois de reiniciar com bash scripts/instalar-servico.sh, o /usage mostra hoje, semana e mês, o gasto por tier e por agente nos últimos 30 dias, e o orçamento. Em 70 % chega um alerta no Telegram; em 100 % a trava entra e só o Ollama continua passando.

🧠 Gestor do Ollama: papéis e preflight

O v3 fala com o Ollama só por HTTP, com o serviço do sistema, nunca subindo um ollama serve paralelo. config/ollama.yaml dá um modelo a cada papel, e é o arquivo mais perigoso do repositório enquanto os dois bots convivem na mesma máquina.

Legenda: se o preflight falhar, a chamada cai para o tier barato e um alerta sai no Telegram. É a diferença entre degradar e travar a máquina.

Papel	Modelo	Por quê
`roteador`	`llama3.2`, `keep_alive: 10m`	classificação em JSON, cerca de 2 s, 4 GB
`geral`	`qwen3.8:27b`, `keep_alive: -1`, residente	mesma tag do v2: um único modelo serve os dois bots
`embed`	`bge-m3`, `keep_alive: 10m`	vetores da memória, 0,7 GB
`pesado`	`llama3.1:70b`, `ativo: false`	42 GB, desligado até o corte

Legenda: no keep_alive, o -1 é número e a duração vai entre aspas, como "10m". O -1 do modelo geral fixa cerca de 17 GB na RAM: é o desenho do plano, e para soltar basta trocar para 10m.

✦ Dica prática

descarregar_alheios: false significa que o v3 nunca descarrega um modelo que ele mesmo não carregou, porque pode ser o modelo que o v2 está usando. Por isso /ollama descarregar <modelo> recusa o que não é dele. Use /ollama status para ver o que está carregado e /ollama preflight <modelo> para perguntar se caberia, antes de trocar qualquer tag.

📡 Canais extras: Slack, WhatsApp e HTTP

Além do Telegram e da CLI, o v3 tem três canais no código. Dois estão desligados de propósito enquanto o v2 é dono do token do Slack e da sessão do número do WhatsApp. O terceiro, o HTTP, está ligado e escuta em 127.0.0.1.

✓ O que já funciona

✓POST /mensagem no canal HTTP dispara agente com permissões, local por padrão.
✓O Slack tem cliente pela Web API e probe de OAuth no doctor, então dá para testar a credencial antes do corte.
✓O dashboard em :3142/ mostra saúde, fila, custo e memória, atualizando a cada 10 s.
✓Toda resposta que sai passa pela guarda de exfiltração, que troca segredo por [REDIGIDO].

✗ O que está fechado

✗SLACK_ENABLED e WHATSAPP_ENABLED em 0: ligar antes do corte briga com o v2.
✗O WhatsApp é um stub que recusa: a implementação real fica para a fase 8, em daemon separado.
✗Expor o HTTP na rede sem HTTP_BIND_V3=0.0.0.0 e DASHBOARD_TOKEN_V3: o endpoint dispara agente com permissões.
✗Agir pelo dashboard: ele é só leitura, quem opera é o chat.

✦ Dica prática

O token do Telegram do v3 é próprio (TELEGRAM_BOT_TOKEN_V3) e o do v2 é recusado no boot. Isso não é excesso de zelo: dois processos chamando getUpdates com o mesmo token brigam pelas mensagens. A regra da coexistência vale para todos os canais, não só para o Telegram.

🗺️ Roadmap: fase 8, fase 10 e o que falta

As fases 0 a 7 estão no ar, e a fase 9 acrescentou o controle da conversa. O que vem depois está escrito, com esforço estimado, mas nenhuma fase começa sozinha. A ordem é sua.

⏱ O que está escrito e ainda não começou

Fase 8, o corte trocar o token de produção, deixar o v2 só leitura por 30 dias e depois arquivar. Critério de paridade: todos os comandos do v2 respondendo no v3, 7 dias sem job perdido e custo semanal medido e abaixo do v2. Só com ordem explícita.
Fase 10, MCP como porta cliente MCP nativo no caminho da resposta direta no Ollama, para o Jarvis local usar ferramentas sem acordar o Claude, e um servidor MCP fino do inemavox como primeiro caso real. Junto vão voz no Telegram, rodapé de uso, /retry e /undo e saúde de skills. Anotado, sem ordem de início.
Fase 11, "Jarvis aprende" fechar o loop de skills, chat temporário, fluxos com portões e cérebro por conversa. Dois itens dependem da decisão sobre o motor de execução.

A lista de limites conhecidos está na seção 15 do README, escrita pelo próprio projeto: o steer não injeta no agente em execução, a tabela jobs ainda não tem política de retenção (cerca de 1.500 linhas por dia só com o cron de lembretes), e a memória guarda a frase inteira em vez de um fato extraído. O WhatsApp real e o Slack ligado também estão nessa lista.

✦ Dica prática

O documento docs/INCORPORAR-V3.md é o cruzamento entre o que o v3 já entrega e o que o Hermes, o openclaw e os outros projetos locais oferecem, com cada lacuna classificada por esforço. Foi de lá que saíram os seis itens da fase 9. Quando quiser propor algo novo, procure primeiro se já está na tabela: a resposta costuma vir com o custo estimado junto.

✅ Resumo do módulo

✓

Agente é pasta - agent.yaml com model (alias opus, sonnet, haiku, fable), effort, read_only, cwd; prompt no CLAUDE.md; registry lê no boot

✓

Especialistas e lead - N especialistas só leitura em paralelo mais um lead com escrita; research é só leitura

✓

Skill é arquivo - só name e description entram no prompt; 15 herdadas do v2; rascunhos em skills/_rascunhos/

✓

Custo tem um único portão - gateway.ts, tiers local, barato e premium, precos.yaml, aviso em 70 % e trava em 100 %

✓

Ollama por papéis - mesmas tags do v2, um grande residente, preflight de RAM, descarregar_alheios: false, pesado desligado

✓

Fase 8 e fase 10 esperam ordem - corte com critério de paridade; MCP nativo, inemavox e voz anotados; limites na seção 15 do README

Fim da trilha:

Você já sabe instalar, operar, conversar e configurar. O que sobra é o que ainda não foi escrito, e isso depende de uma ordem sua.

Módulo anterior: Controle da conversa Voltar ao curso