Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Resolver problemas de cron

Quando uma tarefa de cron não se comporta como você esperava, siga estas verificações na ordem. A maioria dos problemas cai em uma de quatro categorias: horário, entrega, permissões ou carga de skills.

Tarefas que não disparam​

Verificação 1: confirme que a tarefa existe e está ativa​

hermes cron list

Procure a tarefa e confirme que o estado dela é [active] (e não [paused] ou [completed]). Se aparecer [completed], a contagem de repetições pode ter se esgotado — edite a tarefa para reiniciá-la.

Verificação 2: confirme que o agendamento está correto​

Um agendamento mal formatado vira uma execução única em silêncio ou é rejeitado por completo. Teste a sua expressão:

Sua expressãoDeve significar
0 9 * * *9:00 todos os dias
0 9 * * 19:00 de toda segunda-feira
every 2hA cada 2 horas a partir de agora
30mDaqui a 30 minutos
2025-06-01T09:00:001º de junho de 2025 às 9:00 UTC

Se a tarefa dispara uma vez e some da lista, o agendamento é de execução única (30m, 1d ou um carimbo de tempo ISO) — comportamento esperado.

Verificação 3: o gateway está rodando?​

As tarefas de cron são disparadas pela thread de tique em segundo plano do gateway, que tica a cada 60 segundos. Uma sessão comum de conversa na CLI não dispara tarefas de cron automaticamente.

Se você espera que as tarefas disparem sozinhas, precisa de um gateway rodando (hermes gateway em primeiro plano, ou hermes gateway start para o serviço instalado). Para depuração pontual, você pode acionar um tique manualmente com hermes cron tick.

Aplicativo desktop: o backend principal do desktop tem o próprio tique, e ele tica o armazenamento de cron de todos os perfis locais — então as tarefas de um perfil secundário continuam disparando mesmo enquanto o backend daquele perfil está dormindo (o desktop coloca para dormir os backends de perfis ociosos depois de uns 10 minutos). Você não precisa deixar um perfil aberto para as tarefas agendadas dele rodarem.

Verificação 4: confira o relógio e o fuso horário do sistema​

As tarefas usam o fuso horário local. Se o relógio da sua máquina estiver errado ou num fuso diferente do esperado, as tarefas vão disparar na hora errada. Verifique:

date
hermes cron list   # Compare os horários de next_run com a hora local

Falhas de entrega​

Verificação 1: confirme que o destino de entrega está correto​

Os destinos de entrega diferenciam maiúsculas de minúsculas e exigem a plataforma certa configurada. Um destino mal configurado descarta a resposta em silêncio.

DestinoExige
telegramTELEGRAM_BOT_TOKEN em ~/.hermes/.env
discordDISCORD_BOT_TOKEN em ~/.hermes/.env
slackSLACK_BOT_TOKEN em ~/.hermes/.env
whatsappGateway do WhatsApp configurado
signalGateway do Signal configurado
matrixHomeserver Matrix configurado
emailSMTP configurado no config.yaml
smsProvedor de SMS configurado
localPermissão de escrita em ~/.hermes/cron/output/
originEntrega na conversa onde a tarefa foi criada

Outras plataformas suportadas incluem mattermost, homeassistant, dingtalk, feishu, wecom, weixin, bluebubbles, qqbot e webhook. Você também pode mirar uma conversa específica com a sintaxe platform:chat_id (por exemplo, telegram:-1001234567890).

Se a entrega falha, a tarefa mesmo assim roda — ela só não envia para lugar nenhum. Confira no hermes cron list o campo last_error atualizado (quando disponível).

Verificação 2: confira o uso de [SILENT]​

Se a sua tarefa de cron não produz saída, a entrega é suprimida. Se a resposta do agente inclui o marcador de silêncio do cron [SILENT], a entrega também é suprimida. Isso é intencional para tarefas de monitoramento — mas confira se o seu prompt não está suprimindo tudo sem querer.

Use prompts como "responda apenas [SILENT] se nada mudou". Evite pedir que o agente inclua [SILENT] dentro de uma explicação mais longa, porque o cron trata esse marcador como sinal de supressão.

Verificação 3: permissões do token da plataforma​

Cada bot de plataforma de mensagens precisa de permissões específicas para receber mensagens. Se a entrega falha em silêncio:

  • Telegram: o bot precisa ser administrador do grupo/canal de destino
  • Discord: o bot precisa de permissão para enviar no canal de destino
  • Slack: o bot precisa estar adicionado ao workspace e ter o escopo chat:write

Verificação 4: empacotamento da resposta​

Por padrão, as respostas do cron vêm embrulhadas com cabeçalho e rodapé (cron.wrap_response: true no config.yaml). Algumas plataformas ou integrações podem não lidar bem com isso. Para desligar:

cron:
  wrap_response: false

Verificação 5: plataformas atrás de relay (Hermes Cloud / Team Gateway)​

Quando a credencial de uma plataforma mora no conector de relay (por exemplo, Slack ou Discord atrás de um Team Gateway) em vez de estar no seu .env local, o único remetente é o adaptador de relay vivo do gateway em execução — não existe um caminho de entrega independente.

  • Os disparos agendados funcionam enquanto o gateway estiver rodando: o tique dele é o dono da entrega atrás de relay.
  • Um hermes cron run <id> independente encaminha a execução para o gateway automaticamente pelo api_server (POST /api/jobs/{id}/run). Isso exige que a plataforma api_server esteja habilitada com uma API_SERVER_KEY (16 caracteres ou mais). Um contexto --prompt / cronjob(action='run', prompt=...) é encaminhado junto e vale só para aquele disparo.
  • Se o gateway não estiver acessível, a execução falha com um erro do tipo "relay-fronted … start the gateway" em vez do enganoso platform 'slack' not configured/enabled. Suba o gateway e tente de novo.

Falhas na carga de skills​

Verificação 1: confirme que as skills estão instaladas​

hermes skills list

As skills precisam estar instaladas antes de serem anexadas a tarefas de cron. Se faltar alguma skill, instale primeiro com hermes skills install <skill-name> ou pelo /skills na CLI.

Verificação 2: compare o nome da skill com o nome da pasta​

Nomes de skill diferenciam maiúsculas de minúsculas e precisam bater com o nome da pasta da skill instalada. Se a sua tarefa aponta para ai-funding-report mas a pasta da skill é ai-funding-daily-report, confirme o nome exato no hermes skills list.

Verificação 3: skills que exigem ferramentas interativas​

As tarefas de cron rodam com os conjuntos de ferramentas cronjob, messaging e clarify desabilitados. Isso evita criação recursiva de cron, envio direto de mensagens (a entrega fica a cargo do agendador) e perguntas interativas. Se uma skill depende desses conjuntos de ferramentas, ela não vai funcionar num contexto de cron.

Confira a documentação da skill para confirmar que ela funciona em modo não interativo (headless).

Verificação 4: ordem entre várias skills​

Quando você usa várias skills, elas carregam na ordem indicada. Se a Skill A depende do contexto da Skill B, garanta que B carregue primeiro:

/cron add "0 9 * * *" "..." --skill context-skill --skill target-skill

Neste exemplo, context-skill carrega antes de target-skill.

Erros e falhas nas tarefas​

Verificação 1: revise a saída recente da tarefa​

Se uma tarefa rodou e falhou, você pode achar o contexto do erro em:

  1. A conversa em que a tarefa entrega (se a entrega deu certo)
  2. ~/.hermes/logs/agent.log, para as mensagens do agendador (ou errors.log, para os avisos)
  3. Os metadados de last_run da tarefa, via hermes cron list

Verificação 2: padrões comuns de erro​

"No such file or directory" em scripts O caminho de script precisa ser absoluto (ou relativo ao diretório de configuração do Hermes). Verifique:

ls ~/.hermes/scripts/seu-script.py   # Precisa existir
hermes cron edit <job_id> --script ~/.hermes/scripts/seu-script.py

"Skill not found" na hora de executar a tarefa A skill precisa estar instalada na máquina que roda o agendador. Se você troca de máquina, as skills não sincronizam sozinhas — reinstale com hermes skills install <skill-name>.

A tarefa roda mas não entrega nada Provavelmente é problema de destino de entrega (veja Falhas de entrega, acima), ausência de saída, ou uma resposta contendo o marcador de silêncio do cron [SILENT].

A tarefa trava ou estoura o tempo O agendador usa um tempo limite baseado em inatividade (padrão de 600s, configurável pela variável de ambiente HERMES_CRON_TIMEOUT, com 0 para ilimitado). O agente pode rodar o tempo que for, desde que esteja chamando ferramentas ativamente — o cronômetro só dispara depois de inatividade prolongada. Tarefas demoradas devem usar scripts para coletar os dados e entregar só o resultado.

Verificação 3: disputa de trava​

O agendador usa trava em arquivo para evitar tiques sobrepostos. Se duas instâncias do gateway estiverem rodando (ou se uma sessão de CLI conflitar com um gateway), as tarefas podem atrasar ou ser puladas.

Encerre os processos de gateway duplicados:

ps aux | grep hermes
# Encerre os processos duplicados, mantenha só um

Verificação 4: permissões do jobs.json​

As tarefas ficam guardadas em ~/.hermes/cron/jobs.json. Se o seu usuário não puder ler e escrever nesse arquivo, o agendador vai falhar em silêncio:

ls -la ~/.hermes/cron/jobs.json
chmod 600 ~/.hermes/cron/jobs.json   # O arquivo deve pertencer ao seu usuário

Problemas de desempenho​

Subida lenta da tarefa​

Cada tarefa de cron cria uma sessão nova de AIAgent, o que pode envolver autenticação no provedor e carga do modelo. Para agendamentos sensíveis ao horário, deixe uma folga (por exemplo, 0 8 * * * em vez de 0 9 * * *).

Tarefas demais se sobrepondo​

O agendador executa as tarefas em sequência dentro de cada tique. Se várias tarefas vencem ao mesmo tempo, elas rodam uma depois da outra. Considere escalonar os agendamentos (por exemplo, 0 9 * * * e 5 9 * * * em vez de as duas em 0 9 * * *) para evitar atrasos.

Saída de script grande demais​

Scripts que despejam megabytes de saída deixam o agente lento e podem estourar os limites de token. Filtre ou resuma no nível do script — emita só o que o agente precisa para raciocinar.

Comandos de diagnóstico​

hermes cron list                    # Mostra todas as tarefas, estados e horários de next_run
hermes cron run <job_id>            # Agenda para o próximo tique (para testar)
hermes cron edit <job_id>           # Corrige problemas de configuração
hermes logs                         # Vê os logs recentes do Hermes
hermes skills list                  # Confere as skills instaladas

Buscar mais ajuda​

Se você passou por este guia e o problema continua:

  1. Rode a tarefa com hermes cron run <job_id> (dispara no próximo tique do gateway) e observe os erros na saída da conversa
  2. Confira ~/.hermes/logs/agent.log para as mensagens do agendador e ~/.hermes/logs/errors.log para os avisos
  3. Abra uma issue em github.com/NousResearch/hermes-agent com:
    • O ID e o agendamento da tarefa
    • O destino de entrega
    • O que você esperava e o que aconteceu
    • As mensagens de erro relevantes dos logs

Para a referência completa de cron, veja Automatize qualquer coisa com cron e Tarefas agendadas (cron).