Cron job no cPanel: 3 decisões para o script rodar sozinho
O cron job do cPanel resolvido como três decisões, com o menu Common Settings no lugar da sintaxe de asteriscos e um arquivo de log como prova de execução no primeiro dia.

Resposta curta: em três decisões. No cPanel, abra Avançado > Cron Jobs, escolha o intervalo pelo menu Common Settings (comece com 1 hora), escreva o comando com o caminho absoluto do arquivo em vez da URL, e acrescente >> log 2>&1 para ter prova de que rodou.
Neste artigo
- O que o cron job do cPanel executa e o que ele não resolve
- Escolher o intervalo pelo Common Settings em vez de digitar asterisco
- Por que o comando aponta para o caminho no disco, não para a URL
- Como provar que a tarefa rodou gravando um log em arquivo
- Criando a tarefa, clique a clique
- Log vazio ou inexistente: como achar a causa
- Checklist antes de descer o intervalo
Você tem um script que precisa rodar todo dia: limpar uma tabela, enviar um relatório por e-mail, gerar um backup de arquivos, importar um XML de fornecedor. Hoje você abre o navegador e chama o arquivo na mão. O cron job do cPanel faz isso sozinho, no horário que você mandar, sem navegador aberto.
Criar a primeira tarefa agendada não é aprender sintaxe de cron. São três decisões, nesta ordem: de quanto em quanto tempo, qual o caminho completo do arquivo e como provar que rodou. Se você acertar as três, o resto do painel é preenchimento de campo.
O que o cron job do cPanel executa e o que ele não resolve
Na documentação oficial do cPanel, a interface Cron Jobs permite automatizar comandos ou scripts para serem executados em um horário ou intervalo definido (docs.cpanel.net, Cron Jobs).
Três consequências práticas disso:
- O cron executa um comando no servidor, como se você estivesse num terminal. Ele não abre uma página, não tem sessão de navegador, não tem cookie, não tem usuário logado no WordPress.
- Quem roda o comando é o seu usuário do cPanel, com as permissões dele. Nada de permissão de root.
- Se o comando imprimir alguma coisa na tela (um
echo, um aviso do PHP, um erro), o cPanel manda essa saída por e-mail, para o endereço configurado na própria tela de Cron Jobs. Esse comportamento está documentado e é a origem de quase toda caixa de entrada lotada de mensagem de cron.
O que ele não faz: não corrige um script quebrado, não instala dependência que falta e não garante que o ambiente de linha de comando seja igual ao ambiente do navegador. Esses três pontos vêm depois, quando a tarefa já estiver rodando.
Escolher o intervalo pelo Common Settings em vez de digitar asterisco
A tela de Cron Jobs tem cinco campos de tempo (minuto, hora, dia, mês, dia da semana) e, acima deles, um menu chamado Common Settings. A documentação do cPanel descreve esse menu como uma lista de configurações comuns que preenche os campos automaticamente quando você escolhe uma opção.
Use o Common Settings. Sério. No primeiro cron, escolher "Once Per Hour" no menu é mais seguro do que digitar cinco campos de cabeça e descobrir no dia seguinte que o script rodou 1.440 vezes em vez de uma.
Por que o primeiro agendamento deve ser de 1 hora, não de 5 minutos
A tentação é agendar "a cada 5 minutos" para ver funcionar logo. Dois motivos para não fazer isso no primeiro dia:
- Se o script demora mais do que o intervalo, uma execução começa antes de a anterior terminar. Com 5 minutos isso acontece rápido, e você acaba com várias cópias do mesmo processo disputando o banco de dados.
- Erro de caminho ou de permissão vira dezenas de mensagens de erro em uma hora. Com intervalo de uma hora, você lê uma mensagem, corrige, espera a próxima.
Depois que duas ou três execuções seguidas saírem limpas, aí sim você edita a tarefa e desce o intervalo. Trocar o intervalo é um clique em Edit na lista de tarefas existentes.
O que cada um dos cinco campos de tempo significa
| Você quer | Minuto | Hora | Dia | Mês | Dia da semana |
|---|---|---|---|---|---|
| Uma vez por hora, no minuto 0 | 0 | * | * | * | * |
| Todo dia às 3h da manhã | 0 | 3 | * | * | * |
| A cada 5 minutos | */5 | * | * | * | * |
| Toda segunda-feira às 2h | 0 | 2 | * | * | 1 |
O asterisco significa "qualquer valor". Cinco asteriscos seguidos significam "todo minuto de toda hora de todo dia", que é quase nunca o que você quer.
Por que o comando aponta para o caminho no disco, não para a URL
Este é o erro número um de quem vem do navegador. No navegador você chama https://seudominio.com.br/relatorio.php. No cron, o comando certo aponta para o arquivo no disco.
Um exemplo fictício, com o usuário chamado exemplo:
/usr/local/bin/php /home/exemplo/public_html/relatorio.php
Lendo da esquerda para a direita:
/usr/local/bin/phpé o interpretador, o programa que lê e executa o arquivo PHP. Em servidores cPanel esse costuma ser o caminho do PHP de linha de comando, mas confirme o seu: abra o Terminal do cPanel (quando disponível) e rodewhich php. A resposta é o caminho que você deve usar./home/exemplo/public_html/relatorio.phpé o caminho absoluto do script. Troqueexemplopelo seu nome de usuário do cPanel, que aparece no canto da tela do painel, e ajuste a pasta se o arquivo não estiver na raiz do site.
Para descobrir o caminho sem adivinhar: abra o Gerenciador de Arquivos, navegue até o arquivo, clique com o botão direito e escolha a opção que mostra o caminho (ou olhe a barra de endereço da pasta no topo do gerenciador). Copie e cole. Digitar de cabeça é como se perde uma tarde.
Se o seu script é um shell script .sh, o comando é /bin/bash /home/exemplo/caminho/script.sh. Se é Python, é o caminho do Python seguido do arquivo. A lógica é sempre a mesma: interpretador, espaço, caminho absoluto.
Como provar que a tarefa rodou gravando um log em arquivo
Sem log, você fica olhando para o painel tentando adivinhar se rodou. Com log, você abre um arquivo e vê a data da última execução.
No primeiro dia, escreva o comando assim (exemplo fictício, mesmo usuário exemplo):
/usr/local/bin/php /home/exemplo/public_html/relatorio.php >> /home/exemplo/cron-relatorio.log 2>&1
A parte nova:
>>manda tudo que o script imprimiria na tela para o arquivo, acrescentando ao final. Com um>só, cada execução apagaria o conteúdo anterior./home/exemplo/cron-relatorio.logé o arquivo de log. Deixe fora depublic_htmlpara que ninguém leia pela web.2>&1manda também as mensagens de erro para o mesmo arquivo. Sem isso, o erro continua indo por e-mail e o log fica com metade da história.
Depois da hora marcada, abra o Gerenciador de Arquivos, entre na pasta /home/exemplo, clique no .log e use View ou Edit. Se o arquivo existe, o cron executou o comando. Se o arquivo existe mas está vazio, o comando rodou e não imprimiu nada, o que em geral é bom sinal. Se o arquivo não existe, o cron não rodou ou o caminho de destino está errado.
Para marcar a hora de cada execução, faça o próprio script imprimir uma linha com a data no início. Em PHP, echo date('Y-m-d H:i:s') . " ok\n"; resolve e aparece no log.
Quando manter e quando parar o e-mail de notificação do cron
Na parte de cima da tela de Cron Jobs há um campo de e-mail. A documentação do cPanel indica que é para lá que vai a saída dos cron jobs. Duas escolhas razoáveis:
- Nos primeiros dias, deixe um e-mail que você lê. É o aviso mais rápido de que algo quebrou.
- Depois que o log estiver funcionando e a tarefa estável, você pode parar de receber mensagem de uma tarefa específica redirecionando a saída, como no exemplo acima, já que com
>> arquivo 2>&1não sobra nada para enviar.
Criando a tarefa, clique a clique
Gere um backup antes da primeira execução automática
Cron não edita arquivo sozinho, mas o seu script talvez edite. Se ele apaga registros, move arquivos ou altera banco, gere um backup antes da primeira execução automática: no cPanel, Backup ou Assistente de Backup, e baixe pelo menos o banco de dados. Para voltar atrás, restaure esse backup e apague a tarefa pelo botão Delete, na lista Current Cron Jobs. Se quiser só pausar sem perder o comando, clique em Edit e troque o intervalo para algo distante (por exemplo, uma vez por mês), ou coloque um # no começo do campo Command para o servidor ignorar a linha.
Onde fica o Cron Jobs dentro do cPanel
No cPanel, seção Avançado, ícone Cron Jobs. Se não achar, use a busca no topo do painel e digite cron.
Selecione Once Per Hour e confira os campos preenchidos
No menu Common Settings, selecione "Once Per Hour". Os cinco campos abaixo são preenchidos sozinhos. Confira se fazem sentido antes de seguir.
Cole o comando completo no campo Command
No campo Command, cole a linha completa, com interpretador, caminho absoluto e redirecionamento para o log. Releia o nome de usuário e o nome do arquivo caractere por caractere.
Adicione a tarefa e encontre ela em Current Cron Jobs
A tarefa aparece na lista Current Cron Jobs, no fim da página, com botões de Edit e Delete. É essa lista que você vai usar para ajustar o intervalo depois.
Confira o log depois do horário do primeiro disparo
Não fique recarregando o painel. Espere passar o horário do próximo disparo, abra o Gerenciador de Arquivos e leia o .log.
Log vazio ou inexistente: como achar a causa
Tabela de triagem para o primeiro dia:
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| O arquivo de log não foi criado | Caminho do script ou do log errado, ou intervalo ainda não disparou | Confira o caminho no Gerenciador de Arquivos e o horário do servidor |
| Log com "No such file or directory" | Caminho absoluto com erro de digitação ou pasta trocada | Copie o caminho direto do Gerenciador de Arquivos |
| Log com "Permission denied" | Arquivo sem permissão de execução ou pasta inacessível | Ajuste as permissões do arquivo pelo Gerenciador de Arquivos |
| Log com erro do PHP que não aparece no navegador | Ambiente de linha de comando diferente do ambiente web | Rode o mesmo comando no Terminal e compare a saída |
| Script funciona no navegador e falha no cron | Dependência de sessão, de variável de servidor ou de caminho relativo | Troque caminhos relativos por absolutos dentro do script |
As duas últimas linhas são o assunto dos artigos seguintes deste bloco: script que roda no navegador e quebra no cron, escolha do binário certo e dependências que somem na linha de comando. Resolva primeiro o básico: tarefa criada, caminho correto, log sendo escrito.
Checklist antes de descer o intervalo
Antes de trocar "Once Per Hour" por algo mais agressivo, confirme:
- O log registrou pelo menos duas execuções seguidas sem erro.
- Você sabe quanto tempo o script leva. Se não sabe, imprima a data no começo e no fim e compare.
- O intervalo novo é maior que a duração do script, com folga.
- O log não vai crescer sem controle. Um script que imprime muita coisa a cada 5 minutos gera arquivo grande. Trunque o log de vez em quando ou imprima menos.
- Você sabe desligar a tarefa: lista Current Cron Jobs, botão Delete.
Feito isso, a decisão de intervalo vira o que ela deveria ser desde o começo: uma escolha de negócio, não uma aposta.
Referências
- Documentação oficial do cPanel — Cron Jobs. Consultado em 2026-09-16.