🛑 Interruptores: /parar e /retomar
/parar [tudo|agentes|<agente>] [motivo] é o freio de mão. Ele grava um interruptor na tabela prefs (um armazém de chave e valor por chat, onde '*' vale como global), então ele sobrevive a restart do serviço. /parar sozinho lista o que está ligado, com o motivo que você escreveu. /retomar sem alvo desliga todos.
Legenda: quanto mais alto o alvo, mais coisa para. Nenhum deles derruba o serviço, e nenhum deles apaga job: a fila continua sendo o histórico.
✓ O que FAZER
- ✓Escrever o motivo:
/parar agentes revisando o prompt. Ele aparece quando você mandar/pararsozinho. - ✓Usar
/parar <agente>quando o problema é de um especialista só, por exemploops. - ✓Contar até 30 s antes de concluir que não parou: o processo em execução morre na batida seguinte do worker.
- ✓Lembrar que consolidação, ingestão, indexação e backup seguem rodando na lane
ollama.
✗ O que NÃO fazer
- ✗Reiniciar o serviço para "parar": o interruptor persiste e o restart não cancela nada a mais.
- ✗Esquecer o
/retomar: o bot vai continuar mudo amanhã, e o motivo escrito é a única pista. - ✗Achar que job enfileirado antes do
/pararvai rodar: ele falha ao ser pego, com o motivo, sem gastar token. - ✗Contar com
/pararpara bloquear comando de barra: comando sempre responde.
✦ Dica prática
Ligar um interruptor cancela o que está em voo nas lanes chat, agente e io que bate com o alvo. É cancelamento sem corrida: a fila marca o job como cancelado e o worker desiste. O que não é instantâneo é o subprocesso já rodando, porque quem mata é o worker na próxima batida.
🚦 Modos de fila: /fila
Uma mensagem sua chega enquanto outra ainda está sendo respondida. O que fazer com ela é escolha sua, por chat, com /fila collect|followup|steer|interrupt. O padrão é collect. A ideia veio do openclaw, e dois dos quatro modos têm um limite que vale conhecer antes de confiar neles.
| Modo | Comportamento | Diferença para o openclaw |
|---|---|---|
collect | junta mensagens seguidas por 2 s e responde uma vez | igual |
followup | sem janela; se ocupado, entra na fila e responde depois | igual |
steer | se ocupado, substitui o que estava na fila deste chat pela nova, com prioridade alta | o openclaw injeta no agente em execução; com claude -p em subprocesso não dá, então a mensagem só entra quando o agente atual terminar |
interrupt | cancela fila e agentes deste chat (por flow_ref = canal:chat) e responde à nova agora | resposta direta já em voo no Ollama não é abortável: ela termina e é descartada, por um contador de geração por chat |
Legenda: a terceira coluna é a parte honesta. steer muda a fila, não o agente que já está rodando; interrupt joga fora a resposta pronta em vez de interromper a geração.
⏱ Uma mensagem em modo interrupt, segundo a segundo
- t0 você pergunta algo; o roteador manda para agente e o job entra na lane
agente. - t0 + 40 s você percebe que pediu errado e manda a mensagem certa.
- imediato o contador de geração do chat avança e o cancelamento por
flow_refacontece antes de qualquer checagem. - até 30 s o
claude -pcancelado morre na batida seguinte do worker. - em paralelo a nova mensagem já está sendo respondida; se a antiga produzir texto, ele é descartado.
✦ Dica prática
Essa correção do interrupt é a versão 3.2.2. Antes dela, o teste de "tem algo em curso" só olhava a resposta direta, e no caso comum (agente rodando na fila, resposta direta já encerrada) o claude -p seguia vivo. Foi achado em revisão, não em produção. Se você leu documentação antiga, confira a versão com /versao.
⌘ Copiar e rodar: escolher o modo do chat
Objetivo: ver o modo atual, trocar para interrupt e voltar ao padrão, no chat do Telegram com o bot.
/fila
/fila interrupt
/ajuda fila
/fila collectComo verificar: /fila sem argumento responde qual modo está valendo neste chat. Depois de trocar, mande uma pergunta longa e, enquanto ela roda, mande outra: em interrupt a segunda é respondida e a primeira some; em collect as duas viram uma resposta só. O modo fica gravado em prefs, então continua valendo depois de um restart.
🗣️ Persona em três camadas
A voz do bot não vem de um arquivo só. São três camadas, sempre somadas, sempre nesta ordem dentro do prompt. Vale tanto para a resposta direta no Ollama quanto para os agentes. A ideia da alma fixa por agente veio do Hermes.
Legenda: a camada 1 não é negociável, por isso uma personalidade não consegue apagar um limite da identidade. A camada 2 mora com o agente; a 3 é sua, naquele chat.
⌘ Copiar e rodar: trocar a voz deste chat
Objetivo: listar as personalidades disponíveis, ligar uma e voltar ao padrão. Duas já vêm no repositório: curto e professor.
/personality
/personality professor
/personality offComo verificar: sem argumento, o comando lista as disponíveis. Depois de trocar, a próxima resposta já sai na voz nova. Para criar a sua, crie um arquivo personalidades/<nome-que-voce-escolhe>.md e chame por esse nome.
✦ Dica prática
Trocar a personalidade apaga as sessões retomadas daquele chat. Não é efeito colateral: uma sessão --resume de até 6 h faria o agente continuar com a voz antiga. Já o SOUL.md de um agente só entra depois de reiniciar o serviço, porque o registry de agentes lê a pasta uma vez.
🧮 /context: o custo fixo do prompt
/context [detail] [texto] mede, sem chamar modelo de chat, quanto do prompt é cada camada: identidade, persona, USER.md, memória e insights, histórico, skills, regras e a sua mensagem. Mostra os números para a resposta direta e para o agente, que montam prompts diferentes. Sem texto, ele usa a sua última mensagem do chat como consulta.
Legenda: a forma da saída é esta, com a contagem de tokens de cada linha, para os dois caminhos. Os números dependem do seu chat, por isso não estão reproduzidos aqui.
✓ O que FAZER
- ✓Rodar
/contextquando as respostas ficarem caras sem motivo aparente. - ✓Usar
/context detailpara ver item a item o que a memória trouxe. - ✓Passar um texto de consulta quando quiser simular outro assunto:
/context detail <assunto-que-voce-quer-testar>. - ✓Comparar as duas colunas: overhead fixo alto pesa mais na rota de agente.
✗ O que NÃO fazer
- ✗Achar que
/contextgasta token de chat: ele só conta, não chama modelo de conversa. - ✗Temer que consultar infle a memória: o retrieval roda em modo somente leitura e não mexe na saliência.
- ✗Cortar memória boa antes de medir; muitas vezes o peso está no histórico.
- ✗Confundir com
/usage, que é dinheiro gasto, não tamanho de prompt.
🔌 mcp_config por agente
Novo aqui? MCP é o protocolo pelo qual um assistente conversa com ferramentas externas: um servidor MCP expõe ações (ler arquivo, baixar vídeo, consultar API) e o cliente chama. Por padrão, um agente do v3 herda os servidores MCP configurados no seu ~/.claude. A chave mcp_config troca isso por uma lista fechada.
⌘ Copiar e rodar: dar a um agente só os servidores dele
Objetivo: criar o JSON na pasta do agente e apontar o agent.yaml para ele. Os dois exemplos saem de agents/_template/mcp.json.example.
# agents/<id-do-agente>/mcp.json
{
"mcpServers": {
"exemplo-http": { "type": "http", "url": "http://127.0.0.1:8010/mcp" },
"exemplo-stdio": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/<seu-usuario>/projetos"] }
}
}
# agents/<id-do-agente>/agent.yaml
mcp_config: mcp.jsonComo verificar: reinicie o serviço com bash scripts/instalar-servico.sh para o registry reler a pasta. A partir daí o runner sobe o claude -p com --mcp-config <arquivo> --strict-mcp-config, e o agente enxerga apenas esses servidores. O caminho é relativo à pasta do agente.
✓ Quando usar
- ✓Especialista de pesquisa que não deveria ter ferramenta de escrita.
- ✓Agente que precisa de um servidor local específico e de mais nada.
- ✓Quando você quer que o comportamento do agente não mude junto com a sua máquina.
✗ Onde erra
- ✗Caminho absoluto do outro computador: use o nome do arquivo na própria pasta.
- ✗Esperar que valha sem restart: o registry lê a pasta do agente no boot.
- ✗Deixar a chave e esquecer um servidor de que o agente precisa: com
strict, o que não está listado não existe.
Sem a chave mcp_config, nada muda: o agente herda os MCP do usuário, como sempre foi. Um cliente MCP nativo no caminho da resposta direta no Ollama é outra coisa, e está anotado como fase 10 em docs/INCORPORAR-V3.md, sem ordem de início.
📘 /ajuda <comando> e o CHANGELOG
Os cinco comandos deste módulo têm detalhe embutido. /ajuda lista tudo por grupo, incluindo o bloco "Controle da conversa"; /ajuda <comando> abre o texto longo de parar, retomar, fila, personality e context. Para os demais comandos, a resposta diz que não há detalhe e lista os que têm.
⏱ De onde veio este módulo
- 3.2.1, fase 9 "Jarvis obedece" seis itens de
docs/INCORPORAR-V3.md, um commit cada, tudo emprefspela migration 8: interruptores, modos de fila, SOUL e personality,/context,doctor --deepemcp_config. Testes: 187 passando. - 3.2.2 correção do
interruptque não pegava agente em voo, achada em revisão. - 3.2.3 a documentação: seção 9b do README e o
/ajudacom detalhe por comando. É a fonte deste módulo.
✦ Dica prática
Quando a resposta do bot contradiz o que você lembra da documentação, confie no /versao e no CHANGELOG, nessa ordem. Os comandos de controle são novos, e a seção 9b do README é o texto que acompanha o código que está no ar.
✅ Resumo do módulo
/parar tudo|agentes|<agente> [motivo] grava em prefs; comandos e manutenção na lane ollama seguemcollect é o padrão; steer não injeta no agente em voo; interrupt descarta a resposta direta por geraçãoIDENTIDADE.md, SOUL.md do agente (pede restart), personalidades/*.md por chat; trocar apaga a sessão retomadadetail lista os itens; retrieval só leitura--mcp-config <arquivo> --strict-mcp-config; sem a chave, herda os MCP do usuárioPróximo módulo:
4.2 - Agentes, skills, custo e o que vem: a pasta que vira agente, o arquivo que vira skill, os tiers de custo com trava, o gestor do Ollama e o roadmap.