blog
Painéis

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.

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

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
  1. O que o cron job do cPanel executa e o que ele não resolve
  2. Escolher o intervalo pelo Common Settings em vez de digitar asterisco
  3. Por que o comando aponta para o caminho no disco, não para a URL
  4. Como provar que a tarefa rodou gravando um log em arquivo
  5. Criando a tarefa, clique a clique
  6. Log vazio ou inexistente: como achar a causa
  7. 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 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:

  1. 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.
  2. 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:

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:

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:

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:

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

  1. Documentação oficial do cPanel — Cron Jobs. Consultado em 2026-09-16.
Leia também