blog
Painéis

Cron job no cPanel: rodar um arquivo todo dia às 3h30

Guia de entrada para quem nunca agendou nada: o que é cron, por que o asterisco no campo errado faz a tarefa rodar 1.440 vezes por dia e como conferir na manhã seguinte se funcionou.

JR · · 8 min de leitura · 2 tabelas · 2 blocos de código

Resposta curta: use o Cron Jobs do cPanel, em Advanced > Cron Jobs: defina minuto e hora fixos (por exemplo 30 e 3, para 3h30 da manhã), deixe os outros três campos com asterisco e escreva o comando com o caminho completo do interpretador e do arquivo.

Neste artigo
  1. Cron job é um despertador dentro do servidor
  2. As quatro informações que você precisa ter antes de criar a tarefa
  3. Por que cinco asteriscos fazem a tarefa rodar 1.440 vezes por dia
  4. Por que o comando precisa do caminho completo do interpretador
  5. Quando manter o Cron Email ligado e quando silenciar
  6. Três formas de confirmar que a tarefa rodou de madrugada
  7. Seis sintomas comuns e o que fazer em cada um
  8. Teste com um arquivo que não importa antes do arquivo de verdade

Cron job é um despertador dentro do servidor

Imagine um despertador dentro do servidor que hospeda o seu site. Você diz a hora, diz o que deve ser feito quando tocar, e vai dormir. Na hora marcada o servidor acorda sozinho, executa aquilo e volta a dormir. Ninguém precisa estar com o navegador aberto, nem com o computador ligado.

Esse despertador tem nome: cron. É o programa que fica rodando no servidor cuidando do relógio. Cada despertador que você cria dentro dele é um cron job, que em português costuma aparecer como "tarefa agendada" ou "tarefa cron". No cPanel, o painel de controle usado por boa parte das hospedagens, isso fica em Advanced > Cron Jobs (documentação oficial do cPanel).

Usos comuns para quem está começando:

Uma tarefa agendada não cria o arquivo nem decide o que ele faz. Ela só aperta o botão na hora certa. O arquivo precisa existir e funcionar antes.

As quatro informações que você precisa ter antes de criar a tarefa

São quatro informações. Se faltar qualquer uma, pare e consiga antes, porque adivinhar aqui é o que gera erro silencioso.

  1. O caminho completo do arquivo que deve rodar. Não é o endereço do site. É o endereço do arquivo dentro do servidor, algo como /home/usuario/public_html/rotina.php. Você monta esse endereço com duas partes, usando o Gerenciador de Arquivos do painel. Primeira parte: abra a pasta onde o arquivo está e olhe a barra de caminho no topo da tela, que mostra a pasta atual, por exemplo /home/usuario/public_html. Segunda parte: o nome do arquivo exatamente como aparece na lista, por exemplo rotina.php. Junte as duas com uma barra: /home/usuario/public_html + / + rotina.php resulta em /home/usuario/public_html/rotina.php. Copie respeitando maiúsculas e minúsculas, porque o servidor diferencia as duas.
  2. Qual programa entende esse arquivo. Um arquivo .php precisa do PHP. Um .py precisa do Python. Um .sh precisa do shell (o programa do servidor que executa comandos escritos em texto, um atrás do outro). Isso se chama interpretador: o tradutor que lê o seu arquivo e executa o que está escrito nele.
  3. A frequência real. Uma vez por dia? Uma vez por hora? Pergunte a quem pediu a tarefa, e peça o horário.
  4. Um e-mail que você lê. O cPanel permite enviar o resultado de cada execução por e-mail, e nos primeiros dias isso é o seu único retorno.
O que ter em mãos antes de agendarCaminho do arquivoPasta mais nome, no GerenciadorInterpretadorPHP, Python ou shellFrequência e horárioQuem pediu a tarefa defineE-mail que você lêRecebe o resultado de cada execução
As quatro informações a reunir antes de abrir a tela de Cron Jobs.

Por que cinco asteriscos fazem a tarefa rodar 1.440 vezes por dia

A tela do cPanel oferece atalhos prontos ("Once Per Minute", "Once Per Hour", "Once Per Day") e também cinco campos separados: minuto, hora, dia, mês, dia da semana. Quem nunca mexeu nisso costuma preencher os campos com asterisco porque parece inofensivo. Não é.

O asterisco significa todos. Cinco asteriscos seguidos significam: todo minuto, de toda hora, de todo dia. Uma tarefa que deveria rodar uma vez por dia passa a rodar 1.440 vezes por dia. Se ela gera um backup, você acorda com o disco cheio. Se ela envia e-mail, você acorda com a caixa de entrada entupida. E a própria documentação do cPanel alerta que executar uma tarefa com frequência alta demais pode degradar o desempenho do servidor.

A leitura dos cinco campos, da esquerda para a direita:

Campo O que é Exemplo de valor Significado do exemplo
Minuto minuto da hora (0 a 59) 30 aos 30 minutos
Hora hora do dia (0 a 23) 3 às 3 da manhã
Dia dia do mês (1 a 31) * todo dia
Mês mês (1 a 12) * todo mês
Dia da semana 0 a 6, domingo é 0 * qualquer dia da semana

Os cinco valores acima, juntos, significam todo dia às 3h30 da manhã. É o agendamento mais usado por quem só precisa de uma execução diária.

Duas regras práticas:

Por que o comando precisa do caminho completo do interpretador

O campo Command é onde você escreve o que deve acontecer. Ele espera duas coisas, nesta ordem: o caminho completo do interpretador e o caminho completo do arquivo.

Escrever só php rotina.php costuma falhar. A tarefa agendada não roda "de dentro da sua pasta" nem com os mesmos atalhos que você teria num terminal. Ela precisa do endereço inteiro, do começo.

Exemplos fictícios, só para mostrar o formato. Troque usuario e o nome do arquivo pelos seus:

/usr/local/bin/php /home/usuario/public_html/rotina.php
/usr/local/bin/python3 /home/usuario/scripts/relatorio.py

O caminho do interpretador muda de servidor para servidor, inclusive conforme a versão do PHP escolhida na conta. Não copie o exemplo acima achando que vale para todo mundo. Pergunte ao suporte da sua hospedagem qual é o caminho correto do PHP (ou do Python) na sua conta, ou verifique na seção de seleção de versão de PHP do painel. É uma pergunta de uma linha e evita três dias de tarefa que não roda.

Depois de preencher frequência e comando, clique em Add New Cron Job. A tarefa aparece na lista da mesma página, com botões de editar e excluir (cPanel, Cron Jobs).

Quando manter o Cron Email ligado e quando silenciar

No topo da tela de Cron Jobs existe o campo Cron Email. O que você colocar ali recebe a saída de cada execução: as mensagens que o programa imprimiu, inclusive mensagens de erro.

A recomendação para quem está começando:

Um meio-termo que funciona bem: manter o e-mail ligado e criar uma pasta de filtro para essas mensagens. Você não vê no dia a dia, mas tem o histórico quando algo quebrar.

Como confirmar que a tarefa rodouChegou e-mail da execução?Mensagem vazia também contaSe não chegou, olhe o efeitoData de modificação no GerenciadorMudou hoje: tarefa rodouFaltou só preencher o Cron EmailNão mudou: revise o comandoCaminho completo e campo de minutoAinda em dúvida: abra chamadoPeça o log de execução do cron
Ordem de checagem para saber se a tarefa agendada rodou de madrugada.

Três formas de confirmar que a tarefa rodou de madrugada

Agendou às 3h30. São 9h. Rodou?

Três checagens, em ordem de facilidade:

Olhe o e-mail, inclusive o que chegou vazio

Se você preencheu o Cron Email, deve haver uma mensagem com horário próximo ao agendado. Mensagem vazia também é sinal de vida: significa que o comando rodou e não imprimiu nada. Nenhuma mensagem costuma significar que a tarefa não rodou, mas não é prova: o campo Cron Email pode estar vazio, ou o e-mail pode ter caído no spam. Confirme sempre com a checagem 2 antes de concluir.

Olhe o efeito da tarefa, não a tarefa

Toda tarefa útil deixa rastro. Backup gera arquivo novo na pasta. Limpeza faz arquivos sumirem. Rotina de e-mail registra envios. Abra o Gerenciador de Arquivos e confira a data de modificação do que deveria ter mudado. Se a data for de ontem, não rodou.

Peça o log de execução do cron ao suporte

O servidor registra as execuções de cron num arquivo de log (o caderno onde o servidor anota o que aconteceu e a que horas). Esse arquivo normalmente não fica acessível pelo painel do cliente. Abra um chamado dizendo o horário agendado e o comando exato, e peça para verificarem se houve execução. Com o comando em mãos, a resposta costuma ser rápida.

Seis sintomas comuns e o que fazer em cada um

Sintoma Causa provável O que fazer
Nada acontece, nenhum e-mail A tarefa não executou, ou o campo Cron Email está vazio Antes de concluir qualquer coisa, confira o efeito: veja no Gerenciador de Arquivos se a data de modificação do arquivo que deveria mudar é de hoje. Se mudou, só faltou preencher o Cron Email. Se não mudou, a tarefa não rodou: revise frequência e comando
E-mail diz "command not found" Faltou o caminho completo do interpretador Pergunte ao suporte o caminho do PHP/Python e reescreva o comando
E-mail diz "No such file or directory" Caminho do arquivo errado ou arquivo movido Confira o caminho no Gerenciador de Arquivos, letra por letra
Rodou centenas de vezes Campo de minuto com * Troque por um número fixo, como 30
Rodou em horário diferente do esperado Fuso horário do servidor Pergunte ao suporte qual fuso o servidor usa e ajuste a hora
Funciona no navegador, falha no cron O arquivo depende de algo que só existe quando alguém abre o endereço no navegador Peça ao desenvolvedor uma versão do arquivo preparada para linha de comando (quando o servidor executa o arquivo sozinho, sem navegador nenhum)

O caso de "funciona no navegador e falha no cron" confunde muita gente. Quando você abre o arquivo pelo endereço do site, quem executa é o servidor web, a parte do servidor que atende os visitantes do site e entrega as páginas ao navegador. Ela trabalha com um conjunto de configurações próprio. Quando o cron executa, não há visitante nem navegador, e o ambiente é outro. Não é falha da hospedagem: é o mesmo arquivo rodando em dois contextos diferentes.

Teste com um arquivo que não importa antes do arquivo de verdade

Comece pequeno e deliberadamente desnecessário. Crie uma tarefa agendada para daqui a dez minutos, apontando para um arquivo de teste que só escreve uma linha num arquivo de texto. Deixe o Cron Email preenchido. Espere.

Se o e-mail chegar, você aprendeu o mecanismo inteiro em dez minutos e pode apagar a tarefa de teste. Se não chegar, você descobriu o problema com um arquivo que não importa, em vez de descobrir no dia em que o backup real não aconteceu.

Depois disso, troque o caminho do arquivo de teste pelo caminho do arquivo de verdade, ajuste minuto e hora para o horário que você quer, e pronto: a tarefa está no ar. Anote em algum lugar o que você agendou, em que horário e para quê. Daqui a seis meses, essa anotação vale mais que a memória.

Referências

  1. Documentação oficial (cpanel) — Cron Jobs. Consultado em 2026-10-25.
Leia também